From db30a45782fc99fc33656a58e148bbb08213efa9 Mon Sep 17 00:00:00 2001
From: neon <18559658+neonsolstice@users.noreply.github.com>
Date: Mon, 30 Mar 2026 01:18:32 -0600
Subject: [PATCH] test(scanner): bootstrap scanner E2E test infrastructure

---
 .github/workflows/e2e-scanner-file-ops.yml    |   77 +
 .github/workflows/e2e-scanner.yml             |   75 +
 DEVELOPMENT.md                                |   30 +
 .../components/LibraryCreatorScanner.vue      |   12 +-
 .../library/composables/useLibraryCreator.ts  |    2 +-
 package.json                                  |    3 +
 packages/types/src/library.ts                 |   20 +-
 scripts/db/prepare-e2e.sh                     |   13 +
 scripts/test/scanner-e2e.sh                   |   21 +
 scripts/test/scanner-file-ops-e2e.sh          |   21 +
 server/package.json                           |    7 +-
 server/src/db/migrations/0000_baseline.sql    |    2 +-
 .../src/db/migrations/meta/0000_snapshot.json |    4 +-
 server/src/db/migrations/meta/_journal.json   |    2 +-
 server/src/db/schema/libraries.ts             |    2 +-
 .../modules/library/dto/create-library.dto.ts |    2 +-
 .../modules/library/dto/update-library.dto.ts |    2 +-
 .../src/modules/library/library.dto.test.ts   |    2 +
 server/src/modules/library/library.service.ts |   30 +-
 .../scanner/file-event-processor.service.ts   |  116 +-
 .../scanner/file-watcher.service.test.ts      |   42 +-
 .../modules/scanner/file-watcher.service.ts   |  128 +-
 server/src/modules/scanner/lib/walk.test.ts   |    9 +
 server/src/modules/scanner/lib/walk.ts        |    5 +-
 .../src/modules/scanner/scanner.repository.ts |  110 +-
 .../modules/scanner/scanner.service.test.ts   |  266 ++-
 server/src/modules/scanner/scanner.service.ts |  295 ++-
 server/src/scripts/db-prepare-e2e.ts          |  103 ++
 server/test/e2e/scanner-fixture-builder.ts    |   48 +
 server/test/e2e/scanner-harness.ts            |  235 +++
 server/test/scanner-file-ops.e2e-spec.ts      | 1633 +++++++++++++++++
 server/test/scanner.e2e-spec.ts               |  474 +++++
 test-results/server/scanner-e2e-junit.xml     |   75 +
 .../server/scanner-e2e-scenarios.json         |  218 +++
 .../server/scanner-file-ops-e2e-junit.xml     |   83 +
 .../scanner-file-ops-e2e-scenarios.json       |  243 +++
 36 files changed, 4288 insertions(+), 122 deletions(-)
 create mode 100644 .github/workflows/e2e-scanner-file-ops.yml
 create mode 100644 .github/workflows/e2e-scanner.yml
 create mode 100644 scripts/db/prepare-e2e.sh
 create mode 100644 scripts/test/scanner-e2e.sh
 create mode 100644 scripts/test/scanner-file-ops-e2e.sh
 create mode 100644 server/src/scripts/db-prepare-e2e.ts
 create mode 100644 server/test/e2e/scanner-fixture-builder.ts
 create mode 100644 server/test/e2e/scanner-harness.ts
 create mode 100644 server/test/scanner-file-ops.e2e-spec.ts
 create mode 100644 server/test/scanner.e2e-spec.ts
 create mode 100644 test-results/server/scanner-e2e-junit.xml
 create mode 100644 test-results/server/scanner-e2e-scenarios.json
 create mode 100644 test-results/server/scanner-file-ops-e2e-junit.xml
 create mode 100644 test-results/server/scanner-file-ops-e2e-scenarios.json

diff --git a/.github/workflows/e2e-scanner-file-ops.yml b/.github/workflows/e2e-scanner-file-ops.yml
new file mode 100644
index 000000000..609cf7529
--- /dev/null
+++ b/.github/workflows/e2e-scanner-file-ops.yml
@@ -0,0 +1,77 @@
+name: Scanner File Ops E2E
+run-name: ${{ format('Scanner File Ops E2E - {0}', github.ref_name) }}
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 * * *"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  checks: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  NODE_VERSION: "24"
+  PNPM_VERSION: "10"
+  E2E_DATABASE_URL: postgres://projectx:projectx@localhost:5432/projectx_e2e
+  NODE_ENV: test
+  JWT_SECRET: scanner-e2e-secret-1234
+  JWT_EXPIRES_IN: 15m
+  JWT_REFRESH_EXPIRES_IN: 7d
+  BOOKS_PATH: ../local/data
+  APP_URL: http://localhost:5173
+
+jobs:
+  scanner-file-ops-e2e:
+    name: Scanner File Ops E2E
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: projectx
+          POSTGRES_PASSWORD: projectx
+          POSTGRES_DB: projectx
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U projectx"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Set up Node.js and pnpm
+        uses: ./.github/actions/setup-node-pnpm
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+
+      - name: Run scanner file ops e2e suite
+        shell: bash
+        run: pnpm run test:e2e:scanner:file-ops
+
+      - name: Publish test report annotations
+        if: always()
+        uses: EnricoMi/publish-unit-test-result-action@c950f6fb443cb5af20a377fd0dfaa78838901040 # v2
+        with:
+          check_name: Server Scanner File Ops E2E
+          files: test-results/server/scanner-file-ops-e2e-junit.xml
+          fail_on: nothing
+          comment_mode: off
+
+      - name: Upload scanner file ops e2e artifacts
+        if: always()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: scanner-file-ops-e2e-report
+          path: test-results/server
+          retention-days: 7
diff --git a/.github/workflows/e2e-scanner.yml b/.github/workflows/e2e-scanner.yml
new file mode 100644
index 000000000..aa44cc73a
--- /dev/null
+++ b/.github/workflows/e2e-scanner.yml
@@ -0,0 +1,75 @@
+name: Scanner E2E
+run-name: ${{ format('Scanner E2E - {0}', github.ref_name) }}
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  checks: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  NODE_VERSION: "24"
+  PNPM_VERSION: "10"
+  E2E_DATABASE_URL: postgres://projectx:projectx@localhost:5432/projectx_e2e
+  NODE_ENV: test
+  JWT_SECRET: scanner-e2e-secret-1234
+  JWT_EXPIRES_IN: 15m
+  JWT_REFRESH_EXPIRES_IN: 7d
+  BOOKS_PATH: ../local/data
+  APP_URL: http://localhost:5173
+
+jobs:
+  scanner-e2e:
+    name: Scanner E2E
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: projectx
+          POSTGRES_PASSWORD: projectx
+          POSTGRES_DB: projectx
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U projectx"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Set up Node.js and pnpm
+        uses: ./.github/actions/setup-node-pnpm
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+
+      - name: Run scanner e2e suite
+        shell: bash
+        run: pnpm run test:e2e:scanner
+
+      - name: Publish test report annotations
+        if: always()
+        uses: EnricoMi/publish-unit-test-result-action@c950f6fb443cb5af20a377fd0dfaa78838901040 # v2
+        with:
+          check_name: Server Scanner E2E
+          files: test-results/server/scanner-e2e-junit.xml
+          fail_on: nothing
+          comment_mode: off
+
+      - name: Upload scanner e2e artifacts
+        if: always()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: scanner-e2e-report
+          path: test-results/server
+          retention-days: 7
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 21211005f..3a2d81faa 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -115,6 +115,8 @@ pnpm run test              # all tests (server + client)
 pnpm run test:server       # server unit tests only
 pnpm run test:client       # client unit tests only
 pnpm run test:e2e:smoke    # e2e smoke suite (requires running DB)
+pnpm run test:e2e:scanner  # scanner e2e suite (uses dedicated projectx_e2e DB)
+pnpm run test:e2e:scanner:file-ops  # scanner file operation e2e suite
 ```
 
 Watch mode while working on a specific area:
@@ -123,6 +125,34 @@ Watch mode while working on a specific area:
 cd server && pnpm test:watch
 ```
 
+### Scanner e2e details
+
+- `pnpm run test:e2e:scanner` prepares and migrates a dedicated e2e database (`projectx_e2e`) on each run.
+- Local runs auto-start PostgreSQL with `docker-compose.dev.yml` if needed.
+- Results are written to `test-results/server/`:
+  - `scanner-e2e-junit.xml`
+  - `scanner-e2e-scenarios.json`
+
+### Scanner file operation e2e details
+
+- `pnpm run test:e2e:scanner:file-ops` prepares and migrates the same dedicated e2e database (`projectx_e2e`) before running.
+- Local runs auto-start PostgreSQL with `docker-compose.dev.yml` if needed.
+- Results are written to `test-results/server/`:
+  - `scanner-file-ops-e2e-junit.xml`
+  - `scanner-file-ops-e2e-scenarios.json`
+
+### Scanner e2e in CI (manual)
+
+- Open GitHub Actions and run the **Scanner E2E** workflow manually (`workflow_dispatch`).
+- The workflow runs the full scanner scenario matrix against a service-container Postgres instance.
+- It uploads `test-results/server/` as an artifact and publishes JUnit annotations.
+
+### Scanner file operation e2e in CI
+
+- Open GitHub Actions and run the **Scanner File Ops E2E** workflow manually (`workflow_dispatch`) or wait for the nightly run.
+- The workflow runs the full file operation matrix against a service-container Postgres instance.
+- It uploads `test-results/server/` as an artifact and publishes JUnit annotations.
+
 ---
 
 ## Code Quality
diff --git a/client/src/features/library/components/LibraryCreatorScanner.vue b/client/src/features/library/components/LibraryCreatorScanner.vue
index b794d58f8..c5c8a5ba3 100644
--- a/client/src/features/library/components/LibraryCreatorScanner.vue
+++ b/client/src/features/library/components/LibraryCreatorScanner.vue
@@ -74,15 +74,19 @@ function onPatternKeydown(e: KeyboardEvent) {
       <div class="grid grid-cols-1 sm:grid-cols-2 gap-3">
         <button
           class="text-left rounded-lg border p-4 transition-colors"
-          :class="organizationMode === 'auto' ? 'border-primary bg-primary/5 ring-1 ring-primary' : 'border-border bg-card hover:border-primary/40'"
-          @click="handleSelectMode('auto')"
+          :class="
+            organizationMode === 'book_per_folder'
+              ? 'border-primary bg-primary/5 ring-1 ring-primary'
+              : 'border-border bg-card hover:border-primary/40'
+          "
+          @click="handleSelectMode('book_per_folder')"
         >
           <div class="flex items-center gap-2 mb-1.5">
             <span
               class="w-3.5 h-3.5 rounded-full border-2 shrink-0 flex items-center justify-center"
-              :class="organizationMode === 'auto' ? 'border-primary' : 'border-muted-foreground/40'"
+              :class="organizationMode === 'book_per_folder' ? 'border-primary' : 'border-muted-foreground/40'"
             >
-              <span v-if="organizationMode === 'auto'" class="w-1.5 h-1.5 rounded-full bg-primary" />
+              <span v-if="organizationMode === 'book_per_folder'" class="w-1.5 h-1.5 rounded-full bg-primary" />
             </span>
             <span class="text-sm font-semibold text-foreground">Folder as Book</span>
             <span class="ml-auto text-[10px] font-medium text-primary bg-primary/10 px-1.5 py-0.5 rounded">Recommended</span>
diff --git a/client/src/features/library/composables/useLibraryCreator.ts b/client/src/features/library/composables/useLibraryCreator.ts
index 44c8834ae..92fad1e4c 100644
--- a/client/src/features/library/composables/useLibraryCreator.ts
+++ b/client/src/features/library/composables/useLibraryCreator.ts
@@ -24,7 +24,7 @@ function blankForm() {
     metadataPrecedence: [...DEFAULT_METADATA_PRECEDENCE],
     formatPriority: [...DEFAULT_FORMAT_PRIORITY] as string[],
     allowedFormats: [] as string[],
-    organizationMode: 'auto' as OrganizationMode,
+    organizationMode: 'book_per_folder' as OrganizationMode,
     excludePatterns: [] as string[],
     readingThreshold: 0.25,
     markAsFinishedPercentComplete: 98,
diff --git a/package.json b/package.json
index 3f4b1ebb4..30a97b704 100644
--- a/package.json
+++ b/package.json
@@ -32,6 +32,9 @@
     "db:migrate": "pnpm --filter server db:migrate",
     "db:reset": "bash ./scripts/db/reset.sh",
     "db:seed": "bash ./scripts/db/seed.sh",
+    "db:prepare:e2e": "bash ./scripts/db/prepare-e2e.sh",
+    "test:e2e:scanner": "bash ./scripts/test/scanner-e2e.sh",
+    "test:e2e:scanner:file-ops": "bash ./scripts/test/scanner-file-ops-e2e.sh",
     "prepare": "husky"
   },
   "engines": {
diff --git a/packages/types/src/library.ts b/packages/types/src/library.ts
index 84cc81dee..4bcb6a69a 100644
--- a/packages/types/src/library.ts
+++ b/packages/types/src/library.ts
@@ -1,10 +1,22 @@
-export type OrganizationMode = "auto" | "book_per_file" | "book_per_folder";
+export type OrganizationMode = "book_per_file" | "book_per_folder";
 export type CoverAspectRatio = "2/3" | "1/1";
 
 export const DEFAULT_FORMAT_PRIORITY = [
-  "epub", "pdf", "cbz", "cbr", "cb7",
-  "mobi", "azw3", "azw", "fb2",
-  "m4b", "mp3", "m4a", "opus", "ogg", "flac",
+  "epub",
+  "pdf",
+  "cbz",
+  "cbr",
+  "cb7",
+  "mobi",
+  "azw3",
+  "azw",
+  "fb2",
+  "m4b",
+  "mp3",
+  "m4a",
+  "opus",
+  "ogg",
+  "flac",
 ] as const;
 
 export const FORMAT_LABELS: Record<string, string> = {
diff --git a/scripts/db/prepare-e2e.sh b/scripts/db/prepare-e2e.sh
new file mode 100644
index 000000000..898e376b6
--- /dev/null
+++ b/scripts/db/prepare-e2e.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT_DIR"
+
+E2E_DATABASE_URL="${E2E_DATABASE_URL:-${DATABASE_URL:-postgres://projectx:projectx@localhost:5432/projectx_e2e}}"
+
+echo "Preparing dedicated e2e database..."
+DATABASE_URL="$E2E_DATABASE_URL" pnpm --filter server db:prepare:e2e
+
+echo "Applying migrations to e2e database..."
+DATABASE_URL="$E2E_DATABASE_URL" pnpm --filter server db:migrate
diff --git a/scripts/test/scanner-e2e.sh b/scripts/test/scanner-e2e.sh
new file mode 100644
index 000000000..9c9f115ef
--- /dev/null
+++ b/scripts/test/scanner-e2e.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT_DIR"
+
+E2E_DATABASE_URL="${E2E_DATABASE_URL:-${DATABASE_URL:-postgres://projectx:projectx@localhost:5432/projectx_e2e}}"
+JUNIT_OUTPUT="${JUNIT_OUTPUT:-$ROOT_DIR/test-results/server/scanner-e2e-junit.xml}"
+
+if [[ "${CI:-}" != "true" ]]; then
+  echo "Starting local PostgreSQL (dev compose)..."
+  pnpm run db:up
+fi
+
+echo "Resetting and migrating dedicated e2e database..."
+E2E_DATABASE_URL="$E2E_DATABASE_URL" pnpm run db:prepare:e2e
+
+mkdir -p "$(dirname "$JUNIT_OUTPUT")"
+
+echo "Running scanner e2e suite..."
+DATABASE_URL="$E2E_DATABASE_URL" JUNIT_OUTPUT="$JUNIT_OUTPUT" pnpm --filter server test:e2e:scanner
diff --git a/scripts/test/scanner-file-ops-e2e.sh b/scripts/test/scanner-file-ops-e2e.sh
new file mode 100644
index 000000000..6e330ebdb
--- /dev/null
+++ b/scripts/test/scanner-file-ops-e2e.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT_DIR"
+
+E2E_DATABASE_URL="${E2E_DATABASE_URL:-${DATABASE_URL:-postgres://projectx:projectx@localhost:5432/projectx_e2e}}"
+JUNIT_OUTPUT="${JUNIT_OUTPUT:-$ROOT_DIR/test-results/server/scanner-file-ops-e2e-junit.xml}"
+
+if [[ "${CI:-}" != "true" ]]; then
+  echo "Starting local PostgreSQL (dev compose)..."
+  pnpm run db:up
+fi
+
+echo "Resetting and migrating dedicated e2e database..."
+E2E_DATABASE_URL="$E2E_DATABASE_URL" pnpm run db:prepare:e2e
+
+mkdir -p "$(dirname "$JUNIT_OUTPUT")"
+
+echo "Running scanner file operations e2e suite..."
+DATABASE_URL="$E2E_DATABASE_URL" JUNIT_OUTPUT="$JUNIT_OUTPUT" pnpm --filter server test:e2e:scanner:file-ops
diff --git a/server/package.json b/server/package.json
index c9ae16dca..44505d82b 100644
--- a/server/package.json
+++ b/server/package.json
@@ -17,6 +17,7 @@
     "db:generate": "drizzle-kit generate --name",
     "db:migrate": "drizzle-kit migrate",
     "db:migrate:runtime": "node dist/scripts/migrate.js",
+    "db:prepare:e2e": "tsx src/scripts/db-prepare-e2e.ts",
     "db:studio": "drizzle-kit studio",
     "db:seed": "tsx src/scripts/db-seed.ts",
     "pretype-check": "pnpm --filter @projectx/types build",
@@ -24,10 +25,12 @@
     "lint": "pnpm run lint:check",
     "lint:check": "eslint \"{src,apps,libs,test}/**/*.ts\"",
     "lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-    "test": "vitest run",
+    "test": "vitest run --exclude test/scanner.e2e-spec.ts --exclude test/scanner-file-ops.e2e-spec.ts",
     "test:watch": "vitest",
     "test:cov": "vitest run --coverage",
-    "test:e2e": "vitest run test/app.e2e-spec.ts"
+    "test:e2e": "vitest run test/app.e2e-spec.ts",
+    "test:e2e:scanner": "vitest run test/scanner.e2e-spec.ts --reporter=default --reporter=junit --outputFile.junit=${JUNIT_OUTPUT:-../test-results/server/scanner-e2e-junit.xml}",
+    "test:e2e:scanner:file-ops": "vitest run test/scanner-file-ops.e2e-spec.ts --reporter=default --reporter=junit --outputFile.junit=${JUNIT_OUTPUT:-../test-results/server/scanner-file-ops-e2e-junit.xml}"
   },
   "dependencies": {
     "7z-wasm": "^1.2.0",
diff --git a/server/src/db/migrations/0000_baseline.sql b/server/src/db/migrations/0000_baseline.sql
index 573b41306..86915d40b 100644
--- a/server/src/db/migrations/0000_baseline.sql
+++ b/server/src/db/migrations/0000_baseline.sql
@@ -108,7 +108,7 @@ CREATE TABLE "libraries" (
 	"metadata_precedence" jsonb DEFAULT '["folderStructure","embedded","nfoFile","opfFile","sidecar"]'::jsonb NOT NULL,
 	"format_priority" jsonb DEFAULT '["epub","pdf","cbz","cbr","cb7","mobi","azw3","azw","fb2","m4b","mp3","m4a","opus","ogg","flac"]'::jsonb NOT NULL,
 	"allowed_formats" jsonb DEFAULT '[]'::jsonb NOT NULL,
-	"organization_mode" varchar(20) DEFAULT 'auto' NOT NULL,
+	"organization_mode" varchar(20) DEFAULT 'book_per_folder' NOT NULL,
 	"exclude_patterns" jsonb DEFAULT '[]'::jsonb NOT NULL,
 	"reading_threshold" double precision DEFAULT 0.25 NOT NULL,
 	"mark_as_finished_percent_complete" integer DEFAULT 98 NOT NULL,
diff --git a/server/src/db/migrations/meta/0000_snapshot.json b/server/src/db/migrations/meta/0000_snapshot.json
index 758119256..9c11e2455 100644
--- a/server/src/db/migrations/meta/0000_snapshot.json
+++ b/server/src/db/migrations/meta/0000_snapshot.json
@@ -1,5 +1,5 @@
 {
-  "id": "6e69fe23-b05c-4a75-8fff-18a9a402877e",
+  "id": "c7f761cf-14d7-477f-87c2-84e7e901258c",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "version": "7",
   "dialect": "postgresql",
@@ -814,7 +814,7 @@
           "type": "varchar(20)",
           "primaryKey": false,
           "notNull": true,
-          "default": "'auto'"
+          "default": "'book_per_folder'"
         },
         "exclude_patterns": {
           "name": "exclude_patterns",
diff --git a/server/src/db/migrations/meta/_journal.json b/server/src/db/migrations/meta/_journal.json
index 5c8e0173e..3da85f925 100644
--- a/server/src/db/migrations/meta/_journal.json
+++ b/server/src/db/migrations/meta/_journal.json
@@ -5,7 +5,7 @@
     {
       "idx": 0,
       "version": "7",
-      "when": 1774771866207,
+      "when": 1774876625499,
       "tag": "0000_baseline",
       "breakpoints": true
     }
diff --git a/server/src/db/schema/libraries.ts b/server/src/db/schema/libraries.ts
index ae4eadaf2..39420ae68 100644
--- a/server/src/db/schema/libraries.ts
+++ b/server/src/db/schema/libraries.ts
@@ -22,7 +22,7 @@ export const libraries = pgTable('libraries', {
     .notNull()
     .default(['epub', 'pdf', 'cbz', 'cbr', 'cb7', 'mobi', 'azw3', 'azw', 'fb2', 'm4b', 'mp3', 'm4a', 'opus', 'ogg', 'flac']),
   allowedFormats: jsonb('allowed_formats').$type<string[]>().notNull().default([]),
-  organizationMode: varchar('organization_mode', { length: 20 }).notNull().default('auto'),
+  organizationMode: varchar('organization_mode', { length: 20 }).notNull().default('book_per_folder'),
   excludePatterns: jsonb('exclude_patterns').$type<string[]>().notNull().default([]),
 
   // Reading progress thresholds
diff --git a/server/src/modules/library/dto/create-library.dto.ts b/server/src/modules/library/dto/create-library.dto.ts
index 9eb063515..fa35a8a5c 100644
--- a/server/src/modules/library/dto/create-library.dto.ts
+++ b/server/src/modules/library/dto/create-library.dto.ts
@@ -69,7 +69,7 @@ export class CreateLibraryDto {
   allowedFormats?: string[];
 
   @IsOptional()
-  @IsIn(['auto', 'book_per_file', 'book_per_folder'])
+  @IsIn(['book_per_file', 'book_per_folder'])
   organizationMode?: string;
 
   @IsOptional()
diff --git a/server/src/modules/library/dto/update-library.dto.ts b/server/src/modules/library/dto/update-library.dto.ts
index f489d4dae..d66154ca5 100644
--- a/server/src/modules/library/dto/update-library.dto.ts
+++ b/server/src/modules/library/dto/update-library.dto.ts
@@ -71,7 +71,7 @@ export class UpdateLibraryDto {
   allowedFormats?: string[];
 
   @IsOptional()
-  @IsIn(['auto', 'book_per_file', 'book_per_folder'])
+  @IsIn(['book_per_file', 'book_per_folder'])
   organizationMode?: string;
 
   @IsOptional()
diff --git a/server/src/modules/library/library.dto.test.ts b/server/src/modules/library/library.dto.test.ts
index 994c94a58..272a11574 100644
--- a/server/src/modules/library/library.dto.test.ts
+++ b/server/src/modules/library/library.dto.test.ts
@@ -25,6 +25,8 @@ describe('Library DTO validation', () => {
 
   it('CreateLibraryDto validates organization mode', async () => {
     expect(await hasErrors(plainToInstance(CreateLibraryDto, { name: 'x', folders: ['/a'], organizationMode: 'bad' }))).toBe(true);
+    expect(await hasErrors(plainToInstance(CreateLibraryDto, { name: 'x', folders: ['/a'], organizationMode: 'book_per_folder' }))).toBe(false);
+    expect(await hasErrors(plainToInstance(CreateLibraryDto, { name: 'x', folders: ['/a'], organizationMode: 'book_per_file' }))).toBe(false);
   });
 
   it('UpdateLibraryDto allows explicit null fileNamingPattern while validating string values', async () => {
diff --git a/server/src/modules/library/library.service.ts b/server/src/modules/library/library.service.ts
index 2326bdef2..bb9648052 100644
--- a/server/src/modules/library/library.service.ts
+++ b/server/src/modules/library/library.service.ts
@@ -46,7 +46,7 @@ export class LibraryService {
       else foldersByLibrary.set(f.libraryId, [f]);
     }
     return libs.map((lib) => ({
-      ...lib,
+      ...normalizeLibraryOrganizationMode(lib),
       folders: (foldersByLibrary.get(lib.id) ?? []).map(({ id, path, createdAt }) => ({ id, path, createdAt })),
     }));
   }
@@ -55,7 +55,7 @@ export class LibraryService {
     const [library] = await this.libraryRepo.findById(id);
     if (!library) throw new NotFoundException('Library not found');
     const folders = await this.libraryRepo.findFoldersByLibrary(id);
-    return { ...library, folders };
+    return { ...normalizeLibraryOrganizationMode(library), folders };
   }
 
   async create(dto: CreateLibraryDto) {
@@ -70,7 +70,7 @@ export class LibraryService {
       metadataPrecedence: dto.metadataPrecedence ?? ['folderStructure', 'embedded', 'nfoFile', 'opfFile', 'sidecar'],
       formatPriority: dto.formatPriority ?? [...DEFAULT_FORMAT_PRIORITY],
       allowedFormats: dto.allowedFormats ?? [],
-      organizationMode: dto.organizationMode ?? 'auto',
+      organizationMode: dto.organizationMode ?? 'book_per_folder',
       excludePatterns: dto.excludePatterns ?? [],
       coverAspectRatio: dto.coverAspectRatio ?? '2/3',
       readingThreshold: dto.readingThreshold ?? 0.25,
@@ -89,7 +89,7 @@ export class LibraryService {
 
     this.scannerService.startScanAsync(library.id);
 
-    return { ...library, folders: folders.map(([f]) => f) };
+    return { ...normalizeLibraryOrganizationMode(library), folders: folders.map(([f]) => f) };
   }
 
   async update(id: number, dto: UpdateLibraryDto) {
@@ -137,10 +137,14 @@ export class LibraryService {
     }
 
     const shouldRescan =
-      dto.formatPriority !== undefined || dto.allowedFormats !== undefined || dto.excludePatterns !== undefined || folderPaths !== undefined;
+      dto.formatPriority !== undefined ||
+      dto.allowedFormats !== undefined ||
+      dto.excludePatterns !== undefined ||
+      dto.organizationMode !== undefined ||
+      folderPaths !== undefined;
     if (shouldRescan) this.scannerService.startScanAsync(id);
 
-    return { ...updated, folders };
+    return { ...normalizeLibraryOrganizationMode(updated), folders };
   }
 
   async remove(id: number) {
@@ -260,3 +264,17 @@ function pathsOverlap(a: string, b: string): boolean {
   const nb = normalize(b);
   return na.startsWith(nb) || nb.startsWith(na);
 }
+
+function normalizeOrganizationMode(mode: string | null | undefined): 'book_per_file' | 'book_per_folder' {
+  return mode === 'book_per_file' ? 'book_per_file' : 'book_per_folder';
+}
+
+function normalizeLibraryOrganizationMode<T extends Record<string, unknown>>(library: T): T {
+  if (!Object.prototype.hasOwnProperty.call(library, 'organizationMode')) {
+    return library;
+  }
+  return {
+    ...library,
+    organizationMode: normalizeOrganizationMode((library as { organizationMode?: string | null }).organizationMode),
+  };
+}
diff --git a/server/src/modules/scanner/file-event-processor.service.ts b/server/src/modules/scanner/file-event-processor.service.ts
index 42f4f8a95..91fd3bc3a 100644
--- a/server/src/modules/scanner/file-event-processor.service.ts
+++ b/server/src/modules/scanner/file-event-processor.service.ts
@@ -17,11 +17,14 @@ export class FileEventProcessorService {
 
   constructor(private readonly scannerRepo: ScannerRepository) {}
 
-  async handleUnlink(absolutePath: string): Promise<FileEventResult> {
-    const row = await this.scannerRepo.findBookFileByAbsolutePath(absolutePath);
+  async handleUnlink(absolutePath: string, scopeLibraryId?: number): Promise<FileEventResult> {
+    const row =
+      scopeLibraryId == null
+        ? await this.scannerRepo.findBookFileByAbsolutePath(absolutePath)
+        : await this.scannerRepo.findBookFileByAbsolutePath(absolutePath, scopeLibraryId);
     if (!row) return { type: 'noop' };
 
-    const { file, libraryId, primaryFileId } = row;
+    const { file, libraryId: rowLibraryId, primaryFileId } = row;
 
     const shouldReevaluate =
       file.id === primaryFileId ||
@@ -32,7 +35,7 @@ export class FileEventProcessorService {
     if (!shouldReevaluate) {
       await this.scannerRepo.deleteBookFile(file.id);
       this.logger.log(
-        `[scanner.file_event.unlink] [end] libraryId=${libraryId} bookId=${file.bookId} path="${absolutePath.replace(/"/g, '\\"')}" action=remove_non_selected - non-selected file removed`,
+        `[scanner.file_event.unlink] [end] libraryId=${rowLibraryId} bookId=${file.bookId} path="${absolutePath.replace(/"/g, '\\"')}" action=remove_non_selected - non-selected file removed`,
       );
       return { type: 'noop' };
     }
@@ -47,53 +50,63 @@ export class FileEventProcessorService {
       await this.scannerRepo.updateBookPrimaryFile(file.bookId, null);
       await this.scannerRepo.markBooksAsMissing([file.bookId]);
       this.logger.log(
-        `[scanner.file_event.unlink] [end] libraryId=${libraryId} bookId=${file.bookId} path="${absolutePath.replace(/"/g, '\\"')}" action=mark_missing_selected_removed - selected content file removed`,
+        `[scanner.file_event.unlink] [end] libraryId=${rowLibraryId} bookId=${file.bookId} path="${absolutePath.replace(/"/g, '\\"')}" action=mark_missing_selected_removed - selected content file removed`,
       );
-      return { type: 'book-missing', libraryId, bookIds: [file.bookId] };
+      return { type: 'book-missing', libraryId: rowLibraryId, bookIds: [file.bookId] };
     }
 
     await this.scannerRepo.deleteBookFile(file.id);
 
-    const settings = await this.scannerRepo.findLibrarySettings(libraryId);
+    const settings = await this.scannerRepo.findLibrarySettings(rowLibraryId);
     const formatPriority = settings?.formatPriority ?? DEFAULT_FORMAT_PRIORITY;
 
     const winner = this.pickPrimaryFile(remainingContent, formatPriority);
     await this.scannerRepo.updateBookPrimaryFile(file.bookId, winner?.id ?? null);
     this.logger.log(
-      `[scanner.file_event.unlink] [end] libraryId=${libraryId} bookId=${file.bookId} path="${absolutePath.replace(/"/g, '\\"')}" action=reselect_primary format=${winner?.format ?? 'unknown'} - primary file re-selected`,
+      `[scanner.file_event.unlink] [end] libraryId=${rowLibraryId} bookId=${file.bookId} path="${absolutePath.replace(/"/g, '\\"')}" action=reselect_primary format=${winner?.format ?? 'unknown'} - primary file re-selected`,
     );
-    return { type: 'book-restored', libraryId, bookIds: [file.bookId] };
+    return { type: 'book-restored', libraryId: rowLibraryId, bookIds: [file.bookId] };
   }
 
-  async handleUnlinkDir(absolutePath: string): Promise<FileEventResult> {
-    const matched = await this.scannerRepo.findBooksByFolderPath(absolutePath);
+  async handleUnlinkDir(absolutePath: string, scopeLibraryId?: number): Promise<FileEventResult> {
+    const matched =
+      scopeLibraryId == null
+        ? await this.scannerRepo.findBooksByFolderPath(absolutePath)
+        : await this.scannerRepo.findBooksByFolderPath(absolutePath, scopeLibraryId);
     if (matched.length === 0) return { type: 'noop' };
 
     const bookIds = matched.map((b) => b.id);
-    const libraryId = matched[0].libraryId;
+    const matchedLibraryId = matched[0].libraryId;
 
     await this.scannerRepo.markBooksAsMissing(bookIds);
 
     this.logger.log(
-      `[scanner.file_event.unlink_dir] [end] libraryId=${libraryId} path="${absolutePath.replace(/"/g, '\\"')}" missingCount=${bookIds.length} - books marked missing for removed folder`,
+      `[scanner.file_event.unlink_dir] [end] libraryId=${matchedLibraryId} path="${absolutePath.replace(/"/g, '\\"')}" missingCount=${bookIds.length} - books marked missing for removed folder`,
     );
-    return { type: 'book-missing', libraryId, bookIds };
+    return { type: 'book-missing', libraryId: matchedLibraryId, bookIds };
   }
 
-  async handleCreate(absolutePath: string): Promise<FileEventResult> {
+  async handleCreate(absolutePath: string, scopeLibraryId?: number): Promise<FileEventResult> {
     const fileStat = await stat(absolutePath).catch(() => null);
     if (!fileStat) return { type: 'noop' };
 
-    if (fileStat.isDirectory()) return this.handleCreateDir(absolutePath);
+    if (fileStat.isDirectory()) return this.handleCreateDir(absolutePath, scopeLibraryId);
 
     const { role, format } = classifyFile(absolutePath);
     if (role !== 'content') return { type: 'noop' };
 
-    const existing = await this.scannerRepo.findBookFileByAbsolutePath(absolutePath);
+    const existing =
+      scopeLibraryId == null
+        ? await this.scannerRepo.findBookFileByAbsolutePath(absolutePath)
+        : await this.scannerRepo.findBookFileByAbsolutePath(absolutePath, scopeLibraryId);
     if (existing) {
       const book =
-        (await this.scannerRepo.findMissingBookByFolderPath(dirname(absolutePath))) ??
-        (await this.scannerRepo.findMissingBookByFolderPath(absolutePath));
+        (scopeLibraryId == null
+          ? await this.scannerRepo.findMissingBookByFolderPath(dirname(absolutePath))
+          : await this.scannerRepo.findMissingBookByFolderPath(dirname(absolutePath), scopeLibraryId)) ??
+        (scopeLibraryId == null
+          ? await this.scannerRepo.findMissingBookByFolderPath(absolutePath)
+          : await this.scannerRepo.findMissingBookByFolderPath(absolutePath, scopeLibraryId));
       if (!book) return { type: 'noop' };
 
       await this.scannerRepo.updateBookFile(existing.file.id, this.statToFileInfo(fileStat));
@@ -107,7 +120,12 @@ export class FileEventProcessorService {
 
     const folderPath = dirname(absolutePath);
     const book =
-      (await this.scannerRepo.findMissingBookByFolderPath(folderPath)) ?? (await this.scannerRepo.findMissingBookByFolderPath(absolutePath));
+      (scopeLibraryId == null
+        ? await this.scannerRepo.findMissingBookByFolderPath(folderPath)
+        : await this.scannerRepo.findMissingBookByFolderPath(folderPath, scopeLibraryId)) ??
+      (scopeLibraryId == null
+        ? await this.scannerRepo.findMissingBookByFolderPath(absolutePath)
+        : await this.scannerRepo.findMissingBookByFolderPath(absolutePath, scopeLibraryId));
     if (book) {
       const libraryFolderPath = await this.scannerRepo.findLibraryFolderPath(book.libraryFolderId);
       await this.scannerRepo.createBookFile({
@@ -128,7 +146,7 @@ export class FileEventProcessorService {
       return { type: 'book-restored', libraryId: book.libraryId, bookIds: [book.id] };
     }
 
-    return this.detectMovedFile(absolutePath, fileStat);
+    return this.detectMovedFile(absolutePath, fileStat, scopeLibraryId);
   }
 
   async reconcileMissingBooks(libraryIds: number[]): Promise<FileEventResult[]> {
@@ -195,12 +213,29 @@ export class FileEventProcessorService {
     return { type: 'book-restored', libraryId: book.libraryId, bookIds: [book.id] };
   }
 
-  private async detectMovedFile(newAbsolutePath: string, fileStat: Awaited<ReturnType<typeof stat>>): Promise<FileEventResult> {
-    const match = await this.scannerRepo.findBookFileWithContextByIno(Number(fileStat.ino));
+  private async detectMovedFile(
+    newAbsolutePath: string,
+    fileStat: Awaited<ReturnType<typeof stat>>,
+    scopeLibraryId?: number,
+  ): Promise<FileEventResult> {
+    const match =
+      scopeLibraryId == null
+        ? await this.scannerRepo.findBookFileWithContextByIno(Number(fileStat.ino))
+        : await this.scannerRepo.findBookFileWithContextByIno(Number(fileStat.ino), scopeLibraryId);
     if (!match || match.file.absolutePath === newAbsolutePath) return { type: 'noop' };
 
-    const { file, libraryId, folderPath: oldFolderPath, libraryFolderPath } = match;
+    const { file, libraryId: rowLibraryId, folderPath: oldFolderPath, libraryFolderPath } = match;
     const newFolderPath = oldFolderPath === file.absolutePath ? newAbsolutePath : dirname(newAbsolutePath);
+    if (newFolderPath !== oldFolderPath) {
+      const targetBooks = await this.scannerRepo.findBooksByFolderPath(newFolderPath, rowLibraryId);
+      const hasFolderCollision = targetBooks.some((book) => book.id !== file.bookId && book.folderPath === newFolderPath);
+      if (hasFolderCollision) {
+        this.logger.log(
+          `[scanner.file_event.move] [end] libraryId=${rowLibraryId} bookId=${file.bookId} from="${file.absolutePath.replace(/"/g, '\\"')}" to="${newAbsolutePath.replace(/"/g, '\\"')}" action=defer_to_scan collisionFolder="${newFolderPath.replace(/"/g, '\\"')}" - moved file deferred to folder scan`,
+        );
+        return { type: 'noop' };
+      }
+    }
 
     await this.scannerRepo.updateBookFile(file.id, {
       absolutePath: newAbsolutePath,
@@ -214,19 +249,19 @@ export class FileEventProcessorService {
 
     await this.scannerRepo.markBooksAsPresent([file.bookId]);
     this.logger.log(
-      `[scanner.file_event.move] [end] libraryId=${libraryId} bookId=${file.bookId} from="${file.absolutePath.replace(/"/g, '\\"')}" to="${newAbsolutePath.replace(/"/g, '\\"')}" - moved file detected`,
+      `[scanner.file_event.move] [end] libraryId=${rowLibraryId} bookId=${file.bookId} from="${file.absolutePath.replace(/"/g, '\\"')}" to="${newAbsolutePath.replace(/"/g, '\\"')}" - moved file detected`,
     );
-    return { type: 'book-moved', libraryId, bookIds: [file.bookId] };
+    return { type: 'book-moved', libraryId: rowLibraryId, bookIds: [file.bookId] };
   }
 
   private statToFileInfo(s: Awaited<ReturnType<typeof stat>>): { ino: number; sizeBytes: number; mtime: Date } {
     return { ino: Number(s.ino), sizeBytes: Number(s.size), mtime: s.mtime };
   }
 
-  private async detectMovedBooksInDir(dirPath: string): Promise<FileEventResult> {
+  private async detectMovedBooksInDir(dirPath: string, scopeLibraryId?: number): Promise<FileEventResult> {
     const entries = await readdir(dirPath, { recursive: true, withFileTypes: true }).catch(() => []);
     const movedBookIds: number[] = [];
-    let libraryId: number | null = null;
+    let detectedLibraryId: number | null = null;
 
     for (const entry of entries) {
       if (!entry.isFile()) continue;
@@ -237,18 +272,18 @@ export class FileEventProcessorService {
       const s = await stat(fullPath).catch(() => null);
       if (!s) continue;
 
-      const result = await this.detectMovedFile(fullPath, s);
+      const result = await this.detectMovedFile(fullPath, s, scopeLibraryId);
       if (result.type === 'book-moved') {
         movedBookIds.push(...result.bookIds);
-        libraryId = result.libraryId;
+        detectedLibraryId = result.libraryId;
       }
     }
 
-    if (movedBookIds.length === 0 || !libraryId) return { type: 'noop' };
+    if (movedBookIds.length === 0 || !detectedLibraryId) return { type: 'noop' };
     this.logger.log(
-      `[scanner.file_event.move_dir] [end] libraryId=${libraryId} dirPath="${dirPath.replace(/"/g, '\\"')}" movedCount=${movedBookIds.length} - moved books detected in directory`,
+      `[scanner.file_event.move_dir] [end] libraryId=${detectedLibraryId} dirPath="${dirPath.replace(/"/g, '\\"')}" movedCount=${movedBookIds.length} - moved books detected in directory`,
     );
-    return { type: 'book-moved', libraryId, bookIds: movedBookIds };
+    return { type: 'book-moved', libraryId: detectedLibraryId, bookIds: movedBookIds };
   }
 
   private pickPrimaryFile<T extends { id: number; format: string | null; sizeBytes: number | null }>(files: T[], formatPriority: string[]): T | null {
@@ -268,11 +303,14 @@ export class FileEventProcessorService {
     await this.scannerRepo.updateBookPrimaryFile(bookId, winner?.id ?? null);
   }
 
-  private async handleCreateDir(absolutePath: string): Promise<FileEventResult> {
-    const missingBooks = await this.scannerRepo.findMissingBooksByFolderPath(absolutePath);
+  private async handleCreateDir(absolutePath: string, scopeLibraryId?: number): Promise<FileEventResult> {
+    const missingBooks =
+      scopeLibraryId == null
+        ? await this.scannerRepo.findMissingBooksByFolderPath(absolutePath)
+        : await this.scannerRepo.findMissingBooksByFolderPath(absolutePath, scopeLibraryId);
     if (missingBooks.length > 0) {
       const restoredIds: number[] = [];
-      const libraryId = missingBooks[0].libraryId;
+      const matchedLibraryId = missingBooks[0].libraryId;
 
       for (const book of missingBooks) {
         const result = await this.tryRestoreBook(book as { id: number; libraryId: number; libraryFolderId: number; folderPath: string });
@@ -281,12 +319,12 @@ export class FileEventProcessorService {
 
       if (restoredIds.length > 0) {
         this.logger.log(
-          `[scanner.file_event.create_dir] [end] libraryId=${libraryId} path="${absolutePath.replace(/"/g, '\\"')}" restoredCount=${restoredIds.length} - books restored for returned folder`,
+          `[scanner.file_event.create_dir] [end] libraryId=${matchedLibraryId} path="${absolutePath.replace(/"/g, '\\"')}" restoredCount=${restoredIds.length} - books restored for returned folder`,
         );
-        return { type: 'book-restored', libraryId, bookIds: restoredIds };
+        return { type: 'book-restored', libraryId: matchedLibraryId, bookIds: restoredIds };
       }
     }
 
-    return this.detectMovedBooksInDir(absolutePath);
+    return this.detectMovedBooksInDir(absolutePath, scopeLibraryId);
   }
 }
diff --git a/server/src/modules/scanner/file-watcher.service.test.ts b/server/src/modules/scanner/file-watcher.service.test.ts
index c84545a96..f548e353b 100644
--- a/server/src/modules/scanner/file-watcher.service.test.ts
+++ b/server/src/modules/scanner/file-watcher.service.test.ts
@@ -1,3 +1,7 @@
+import { mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
 import { FileWatcherService } from './file-watcher.service';
 import { FileEventProcessorService } from './file-event-processor.service';
 import { ScanGateway } from './scan.gateway';
@@ -20,6 +24,7 @@ function makeService() {
   const scannerService = {
     startScanAsync: vi.fn(),
     scanBookFolderAsync: vi.fn(),
+    isScanRunning: vi.fn().mockReturnValue(false),
   } as unknown as ScannerService;
 
   const db = {} as any;
@@ -51,8 +56,8 @@ describe('process()', () => {
 
     await (service as any).process('delete', '/books/Author', 3);
 
-    expect(processor.handleUnlink).toHaveBeenCalledWith('/books/Author');
-    expect(processor.handleUnlinkDir).toHaveBeenCalledWith('/books/Author');
+    expect(processor.handleUnlink).toHaveBeenCalledWith('/books/Author', 3);
+    expect(processor.handleUnlinkDir).toHaveBeenCalledWith('/books/Author', 3);
     expect(gateway.emitBookMissing).toHaveBeenCalledWith({ libraryId: 3, bookIds: [20] });
   });
 
@@ -63,7 +68,7 @@ describe('process()', () => {
 
     await (service as any).process('create', '/books/Author/book.epub', 1);
 
-    expect(processor.handleCreate).toHaveBeenCalledWith('/books/Author/book.epub');
+    expect(processor.handleCreate).toHaveBeenCalledWith('/books/Author/book.epub', 1);
     expect((gateway as any).emitBookRestored).toHaveBeenCalledWith({ libraryId: 1, bookIds: [7] });
     expect(gateway.emitBookMissing).not.toHaveBeenCalled();
   });
@@ -78,6 +83,37 @@ describe('process()', () => {
     expect(scannerService.startScanAsync).not.toHaveBeenCalled();
   });
 
+  it('starts a full scan when handleCreate noop targets a directory', async () => {
+    const { service, scannerService } = makeService();
+    const tempDir = await mkdtemp(join(tmpdir(), 'watcher-dir-create-'));
+
+    try {
+      await (service as any).process('create', tempDir, 8);
+      expect(scannerService.startScanAsync).toHaveBeenCalledWith(8);
+      expect(scannerService.scanBookFolderAsync).not.toHaveBeenCalled();
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('suppresses folder scan for file creates under a recently created directory while full scan is running', async () => {
+    const { service, scannerService } = makeService();
+    const scheduleFolderScanSpy = vi.spyOn(service as any, 'scheduleFolderScan');
+    const tempDir = await mkdtemp(join(tmpdir(), 'watcher-dir-suppress-'));
+    const nestedFile = join(tempDir, 'book.epub');
+
+    try {
+      await (service as any).process('create', tempDir, 9);
+      (scannerService.isScanRunning as vi.Mock).mockReturnValue(true);
+      await (service as any).process('create', nestedFile, 9);
+
+      expect(scannerService.startScanAsync).toHaveBeenCalledWith(9);
+      expect(scheduleFolderScanSpy).not.toHaveBeenCalled();
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
   it('schedules a folder scan and emits book-moved when handleCreate returns book-moved', async () => {
     const { service, processor, gateway, scannerService } = makeService();
     const scheduleFolderScanSpy = vi.spyOn(service as any, 'scheduleFolderScan');
diff --git a/server/src/modules/scanner/file-watcher.service.ts b/server/src/modules/scanner/file-watcher.service.ts
index cce13ab6c..44ef2e9cd 100644
--- a/server/src/modules/scanner/file-watcher.service.ts
+++ b/server/src/modules/scanner/file-watcher.service.ts
@@ -1,7 +1,8 @@
 import { Inject, Injectable, Logger, OnApplicationBootstrap, OnModuleDestroy } from '@nestjs/common';
 import { eq } from 'drizzle-orm';
 import { NodePgDatabase } from 'drizzle-orm/node-postgres';
-import { dirname } from 'path';
+import { stat } from 'fs/promises';
+import { dirname, sep } from 'path';
 import type { AsyncSubscription } from '@parcel/watcher';
 
 import { DB } from '../../db';
@@ -17,6 +18,8 @@ type EventType = 'delete' | 'create';
 
 const DEBOUNCE_MS = 500;
 const SCAN_DEBOUNCE_MS = 3_000;
+const DIR_CREATE_SUPPRESS_MS = 6_000;
+const CROSS_LIBRARY_RESCAN_DEBOUNCE_MS = 1_500;
 const RECONCILE_MS = 30 * 60 * 1_000;
 
 @Injectable()
@@ -24,7 +27,10 @@ export class FileWatcherService implements OnApplicationBootstrap, OnModuleDestr
   private readonly logger = new Logger(FileWatcherService.name);
   private readonly subscriptions = new Map<number, AsyncSubscription[]>();
   private readonly pendingTimers = new Map<string, { timer: ReturnType<typeof setTimeout>; type: EventType; libraryId: number }>();
-  private readonly pendingFolderScanTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly pendingFolderScanTimers = new Map<string, { timer: ReturnType<typeof setTimeout>; libraryId: number }>();
+  private readonly pendingLibraryRescanTimers = new Map<number, ReturnType<typeof setTimeout>>();
+  private readonly suppressedDirScans = new Map<number, Set<string>>();
+  private readonly suppressedDirScanTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private reconcileTimer: ReturnType<typeof setInterval> | null = null;
 
   constructor(
@@ -76,8 +82,13 @@ export class FileWatcherService implements OnApplicationBootstrap, OnModuleDestr
       if (this.reconcileTimer) clearInterval(this.reconcileTimer);
       for (const entry of this.pendingTimers.values()) clearTimeout(entry.timer);
       this.pendingTimers.clear();
-      for (const timer of this.pendingFolderScanTimers.values()) clearTimeout(timer);
+      for (const entry of this.pendingFolderScanTimers.values()) clearTimeout(entry.timer);
       this.pendingFolderScanTimers.clear();
+      for (const timer of this.pendingLibraryRescanTimers.values()) clearTimeout(timer);
+      this.pendingLibraryRescanTimers.clear();
+      for (const timer of this.suppressedDirScanTimers.values()) clearTimeout(timer);
+      this.suppressedDirScanTimers.clear();
+      this.suppressedDirScans.clear();
       for (const subs of this.subscriptions.values()) {
         for (const sub of subs) await sub.unsubscribe();
       }
@@ -146,10 +157,11 @@ export class FileWatcherService implements OnApplicationBootstrap, OnModuleDestr
             );
             return;
           }
-          for (const event of events) {
-            if (event.type === 'delete' || event.type === 'create') {
-              this.schedule(event.type, event.path, libraryId);
-            }
+          for (const fsEvent of events) {
+            const normalizedType: EventType | null =
+              fsEvent.type === 'delete' ? 'delete' : fsEvent.type === 'create' || fsEvent.type === 'update' ? 'create' : null;
+            if (!normalizedType) continue;
+            this.schedule(normalizedType, fsEvent.path, libraryId);
           }
         });
         subs.push(sub);
@@ -181,6 +193,13 @@ export class FileWatcherService implements OnApplicationBootstrap, OnModuleDestr
       }
       for (const sub of existing) await sub.unsubscribe();
       this.subscriptions.delete(libraryId);
+      this.clearPendingTimersForLibrary(libraryId);
+      const pendingRescan = this.pendingLibraryRescanTimers.get(libraryId);
+      if (pendingRescan) {
+        clearTimeout(pendingRescan);
+        this.pendingLibraryRescanTimers.delete(libraryId);
+      }
+      this.clearLibraryFolderScanSuppressions(libraryId);
       this.logger.log(`[${event}] [end] libraryId=${libraryId} durationMs=${Date.now() - startedAt} hadWatcher=true - watcher stop completed`);
     } catch (err) {
       const errorClass = err instanceof Error ? err.name : 'Error';
@@ -195,12 +214,85 @@ export class FileWatcherService implements OnApplicationBootstrap, OnModuleDestr
   private scheduleFolderScan(filePath: string, libraryId: number): void {
     const bookFolder = dirname(filePath);
     const existing = this.pendingFolderScanTimers.get(bookFolder);
-    if (existing) clearTimeout(existing);
+    if (existing) clearTimeout(existing.timer);
     const timer = setTimeout(() => {
       this.pendingFolderScanTimers.delete(bookFolder);
       this.scannerService.scanBookFolderAsync(filePath, libraryId);
     }, SCAN_DEBOUNCE_MS);
-    this.pendingFolderScanTimers.set(bookFolder, timer);
+    this.pendingFolderScanTimers.set(bookFolder, { timer, libraryId });
+  }
+
+  private clearPendingTimersForLibrary(libraryId: number): void {
+    for (const [path, entry] of this.pendingTimers.entries()) {
+      if (entry.libraryId !== libraryId) continue;
+      clearTimeout(entry.timer);
+      this.pendingTimers.delete(path);
+    }
+
+    for (const [folderPath, entry] of this.pendingFolderScanTimers.entries()) {
+      if (entry.libraryId !== libraryId) continue;
+      clearTimeout(entry.timer);
+      this.pendingFolderScanTimers.delete(folderPath);
+    }
+  }
+
+  private scheduleCrossLibraryRescan(sourceLibraryId: number): void {
+    for (const libraryId of this.subscriptions.keys()) {
+      if (libraryId === sourceLibraryId) continue;
+      const existing = this.pendingLibraryRescanTimers.get(libraryId);
+      if (existing) clearTimeout(existing);
+
+      const timer = setTimeout(() => {
+        this.pendingLibraryRescanTimers.delete(libraryId);
+        this.scannerService.startScanAsync(libraryId);
+      }, CROSS_LIBRARY_RESCAN_DEBOUNCE_MS);
+      this.pendingLibraryRescanTimers.set(libraryId, timer);
+    }
+  }
+
+  private suppressFolderScansForDir(dirPath: string, libraryId: number): void {
+    const key = `${libraryId}:${dirPath}`;
+    const existingTimer = this.suppressedDirScanTimers.get(key);
+    if (existingTimer) clearTimeout(existingTimer);
+
+    let librarySet = this.suppressedDirScans.get(libraryId);
+    if (!librarySet) {
+      librarySet = new Set<string>();
+      this.suppressedDirScans.set(libraryId, librarySet);
+    }
+    librarySet.add(dirPath);
+
+    const timer = setTimeout(() => {
+      this.suppressedDirScanTimers.delete(key);
+      const currentSet = this.suppressedDirScans.get(libraryId);
+      if (!currentSet) return;
+      currentSet.delete(dirPath);
+      if (currentSet.size === 0) {
+        this.suppressedDirScans.delete(libraryId);
+      }
+    }, DIR_CREATE_SUPPRESS_MS);
+    this.suppressedDirScanTimers.set(key, timer);
+  }
+
+  private clearLibraryFolderScanSuppressions(libraryId: number): void {
+    const prefix = `${libraryId}:`;
+    for (const [key, timer] of this.suppressedDirScanTimers.entries()) {
+      if (!key.startsWith(prefix)) continue;
+      clearTimeout(timer);
+      this.suppressedDirScanTimers.delete(key);
+    }
+    this.suppressedDirScans.delete(libraryId);
+  }
+
+  private isFolderScanSuppressed(filePath: string, libraryId: number): boolean {
+    const suppressedDirs = this.suppressedDirScans.get(libraryId);
+    if (!suppressedDirs) return false;
+    for (const dirPath of suppressedDirs) {
+      if (filePath === dirPath || filePath.startsWith(`${dirPath}${sep}`)) {
+        return true;
+      }
+    }
+    return false;
   }
 
   private schedule(type: EventType, path: string, libraryId: number): void {
@@ -220,23 +312,33 @@ export class FileWatcherService implements OnApplicationBootstrap, OnModuleDestr
   private async process(type: EventType, path: string, libraryId: number): Promise<void> {
     let result: FileEventResult;
     if (type === 'create') {
-      result = await this.processor.handleCreate(path);
+      result = await this.processor.handleCreate(path, libraryId);
       if (result.type === 'noop') {
+        const pathStat = await stat(path).catch(() => null);
+        if (pathStat?.isDirectory()) {
+          this.suppressFolderScansForDir(path, libraryId);
+          this.scannerService.startScanAsync(libraryId);
+          return;
+        }
         // Only schedule a scan for unrecognised content-format files. Supplementary
         // files (covers, metadata, .lit, etc.) don't need a full scan on creation.
         const { role } = classifyFile(path);
-        if (role === 'content') this.scheduleFolderScan(path, libraryId);
+        if (role === 'content') {
+          if (this.isFolderScanSuppressed(path, libraryId) && this.scannerService.isScanRunning(libraryId)) return;
+          this.scheduleFolderScan(path, libraryId);
+        }
         return;
       }
     } else {
-      result = await this.processor.handleUnlink(path);
+      result = await this.processor.handleUnlink(path, libraryId);
       if (result.type === 'noop') {
-        result = await this.processor.handleUnlinkDir(path);
+        result = await this.processor.handleUnlinkDir(path, libraryId);
       }
     }
 
     if (result.type === 'book-missing') {
       this.gateway.emitBookMissing({ libraryId: result.libraryId, bookIds: result.bookIds });
+      if (type === 'delete') this.scheduleCrossLibraryRescan(result.libraryId);
     } else if (result.type === 'book-restored') {
       this.gateway.emitBookRestored({ libraryId: result.libraryId, bookIds: result.bookIds });
     } else if (result.type === 'book-moved') {
diff --git a/server/src/modules/scanner/lib/walk.test.ts b/server/src/modules/scanner/lib/walk.test.ts
index f0d7b1d47..08861fa9b 100644
--- a/server/src/modules/scanner/lib/walk.test.ts
+++ b/server/src/modules/scanner/lib/walk.test.ts
@@ -360,6 +360,15 @@ describe('disc folder flattening', () => {
     const candidates = await findBookCandidates(root);
     expect(candidates).toHaveLength(2);
   });
+
+  it('does NOT treat names like "Discography" as disc directories', async () => {
+    await file('AudioBook/Discography/01.mp3');
+    await file('AudioBook/cover.jpg');
+
+    const candidates = await findBookCandidates(root);
+    expect(candidates).toHaveLength(1);
+    expect(candidates[0].folderPath).toBe(join(root, 'AudioBook', 'Discography'));
+  });
 });
 
 // ── STEM-NAMED AUDIO SUBFOLDER FLATTENING ────────────────────────────────────
diff --git a/server/src/modules/scanner/lib/walk.ts b/server/src/modules/scanner/lib/walk.ts
index e58a54631..a388c158c 100644
--- a/server/src/modules/scanner/lib/walk.ts
+++ b/server/src/modules/scanner/lib/walk.ts
@@ -18,8 +18,9 @@ export interface BookCandidate {
 
 const MAX_PATH_LENGTH = 4096;
 
-// Matches common disc subdirectory names: "CD 1", "Disc 2", "Disk 3", "Part 2", "Side A"
-const DISC_DIR_PATTERN = /^(?:cd|disc|disk|part|side)\s*[\dA-Za-z]+$/i;
+// Matches common disc subdirectory names: "CD 1", "Disc 2", "Disk03", "Part A", "Side IV"
+// but avoids broad matches like "Discography".
+const DISC_DIR_PATTERN = /^(?:cd|disc|disk|part|side)(?:[\s_-]*(?:\d+|[A-Za-z]|[IVXLCM]+))$/i;
 
 function isDiscDirectory(name: string): boolean {
   return DISC_DIR_PATTERN.test(name);
diff --git a/server/src/modules/scanner/scanner.repository.ts b/server/src/modules/scanner/scanner.repository.ts
index ba85a4df1..c398da64c 100644
--- a/server/src/modules/scanner/scanner.repository.ts
+++ b/server/src/modules/scanner/scanner.repository.ts
@@ -162,37 +162,40 @@ export class ScannerRepository {
     return file;
   }
 
-  async findBookFileByAbsolutePath(absolutePath: string) {
+  async findBookFileByAbsolutePath(absolutePath: string, libraryId?: number) {
+    const whereClause =
+      libraryId == null ? eq(bookFiles.absolutePath, absolutePath) : and(eq(bookFiles.absolutePath, absolutePath), eq(books.libraryId, libraryId));
     const [row] = await this.db
       .select({ file: bookFiles, libraryId: books.libraryId, primaryFileId: books.primaryFileId })
       .from(bookFiles)
       .innerJoin(books, eq(books.id, bookFiles.bookId))
-      .where(eq(bookFiles.absolutePath, absolutePath))
+      .where(whereClause)
       .limit(1);
     return row ?? null;
   }
 
-  async findBooksByFolderPath(folderPath: string) {
-    return this.db
-      .select()
-      .from(books)
-      .where(or(eq(books.folderPath, folderPath), like(books.folderPath, folderPath + '/%')));
+  async findBooksByFolderPath(folderPath: string, libraryId?: number) {
+    const folderScope = or(eq(books.folderPath, folderPath), like(books.folderPath, folderPath + '/%'));
+    const whereClause = libraryId == null ? folderScope : and(eq(books.libraryId, libraryId), folderScope);
+    return this.db.select().from(books).where(whereClause);
   }
 
-  async findMissingBookByFolderPath(folderPath: string) {
-    const [row] = await this.db
-      .select()
-      .from(books)
-      .where(and(eq(books.folderPath, folderPath), eq(books.status, 'missing')))
-      .limit(1);
+  async findMissingBookByFolderPath(folderPath: string, libraryId?: number) {
+    const whereClause =
+      libraryId == null
+        ? and(eq(books.folderPath, folderPath), eq(books.status, 'missing'))
+        : and(eq(books.libraryId, libraryId), eq(books.folderPath, folderPath), eq(books.status, 'missing'));
+    const [row] = await this.db.select().from(books).where(whereClause).limit(1);
     return row ?? null;
   }
 
-  async findMissingBooksByFolderPath(folderPath: string) {
-    return this.db
-      .select()
-      .from(books)
-      .where(and(or(eq(books.folderPath, folderPath), like(books.folderPath, folderPath + '/%')), eq(books.status, 'missing')));
+  async findMissingBooksByFolderPath(folderPath: string, libraryId?: number) {
+    const folderScope = or(eq(books.folderPath, folderPath), like(books.folderPath, folderPath + '/%'));
+    const whereClause =
+      libraryId == null
+        ? and(folderScope, eq(books.status, 'missing'))
+        : and(eq(books.libraryId, libraryId), folderScope, eq(books.status, 'missing'));
+    return this.db.select().from(books).where(whereClause);
   }
 
   async findMissingBooksForLibraries(libraryIds: number[]) {
@@ -208,6 +211,21 @@ export class ScannerRepository {
     await this.db.update(books).set({ status: 'present', updatedAt: new Date() }).where(inArray(books.id, bookIds));
   }
 
+  async moveBookToLibrary(bookId: number, libraryId: number, libraryFolderId: number, folderPath: string) {
+    const [book] = await this.db
+      .update(books)
+      .set({
+        libraryId,
+        libraryFolderId,
+        folderPath,
+        status: 'present',
+        updatedAt: new Date(),
+      })
+      .where(eq(books.id, bookId))
+      .returning();
+    return book ?? null;
+  }
+
   async findBookFilesByBookId(bookId: number) {
     return this.db.select().from(bookFiles).where(eq(bookFiles.bookId, bookId));
   }
@@ -221,7 +239,8 @@ export class ScannerRepository {
     await this.db.delete(bookFiles).where(eq(bookFiles.id, id));
   }
 
-  async findBookFileWithContextByIno(ino: number) {
+  async findBookFileWithContextByIno(ino: number, libraryId?: number) {
+    const whereClause = libraryId == null ? eq(bookFiles.ino, ino) : and(eq(bookFiles.ino, ino), eq(books.libraryId, libraryId));
     const [row] = await this.db
       .select({
         file: bookFiles,
@@ -233,7 +252,58 @@ export class ScannerRepository {
       .from(bookFiles)
       .innerJoin(books, eq(books.id, bookFiles.bookId))
       .innerJoin(libraryFolders, eq(libraryFolders.id, bookFiles.libraryFolderId))
-      .where(eq(bookFiles.ino, ino))
+      .where(whereClause)
+      .limit(1);
+    return row ?? null;
+  }
+
+  async findMissingBookFileWithContextByIno(ino: number) {
+    const [row] = await this.db
+      .select({
+        file: bookFiles,
+        libraryId: books.libraryId,
+        bookStatus: books.status,
+        folderPath: books.folderPath,
+        libraryFolderPath: libraryFolders.path,
+      })
+      .from(bookFiles)
+      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(libraryFolders, eq(libraryFolders.id, bookFiles.libraryFolderId))
+      .where(and(eq(bookFiles.ino, ino), eq(books.status, 'missing')))
+      .limit(1);
+    return row ?? null;
+  }
+
+  async findBookFileWithContextByHash(hash: string) {
+    const [row] = await this.db
+      .select({
+        file: bookFiles,
+        libraryId: books.libraryId,
+        bookStatus: books.status,
+        folderPath: books.folderPath,
+        libraryFolderPath: libraryFolders.path,
+      })
+      .from(bookFiles)
+      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(libraryFolders, eq(libraryFolders.id, bookFiles.libraryFolderId))
+      .where(eq(bookFiles.hash, hash))
+      .limit(1);
+    return row ?? null;
+  }
+
+  async findMissingBookFileWithContextByHash(hash: string) {
+    const [row] = await this.db
+      .select({
+        file: bookFiles,
+        libraryId: books.libraryId,
+        bookStatus: books.status,
+        folderPath: books.folderPath,
+        libraryFolderPath: libraryFolders.path,
+      })
+      .from(bookFiles)
+      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(libraryFolders, eq(libraryFolders.id, bookFiles.libraryFolderId))
+      .where(and(eq(bookFiles.hash, hash), eq(books.status, 'missing')))
       .limit(1);
     return row ?? null;
   }
diff --git a/server/src/modules/scanner/scanner.service.test.ts b/server/src/modules/scanner/scanner.service.test.ts
index 2c01c0505..00787c97a 100644
--- a/server/src/modules/scanner/scanner.service.test.ts
+++ b/server/src/modules/scanner/scanner.service.test.ts
@@ -69,9 +69,12 @@ function makeRepo(overrides: Record<string, unknown> = {}) {
   return {
     failAllRunningJobs: vi.fn().mockResolvedValue(undefined),
     findLibraryFolders: vi.fn().mockResolvedValue([{ id: 1, path: '/library', libraryId: 1 }]),
-    findLibrarySettings: vi
-      .fn()
-      .mockResolvedValue({ allowedFormats: [], formatPriority: DEFAULT_FORMAT_PRIORITY, excludePatterns: [], organizationMode: 'auto' }),
+    findLibrarySettings: vi.fn().mockResolvedValue({
+      allowedFormats: [],
+      formatPriority: DEFAULT_FORMAT_PRIORITY,
+      excludePatterns: [],
+      organizationMode: 'book_per_folder',
+    }),
     createScanJob: vi.fn().mockResolvedValue({ id: 100 }),
     completeScanJob: vi.fn().mockResolvedValue(undefined),
     failScanJob: vi.fn().mockResolvedValue(undefined),
@@ -84,9 +87,24 @@ function makeRepo(overrides: Record<string, unknown> = {}) {
     createBookFile: vi.fn().mockResolvedValue(makeBookFile()),
     updateBookFile: vi.fn().mockResolvedValue(makeBookFile()),
     findBookFileByHash: vi.fn().mockResolvedValue(null),
+    findBookFileWithContextByIno: vi.fn().mockResolvedValue(null),
+    findMissingBookFileWithContextByIno: vi.fn().mockResolvedValue(null),
+    findBookFileWithContextByHash: vi.fn().mockResolvedValue(null),
+    findMissingBookFileWithContextByHash: vi.fn().mockResolvedValue(null),
+    moveBookToLibrary: vi.fn().mockImplementation((bookId: number, libraryId: number, libraryFolderId: number, folderPath: string) =>
+      Promise.resolve({
+        id: bookId,
+        libraryId,
+        libraryFolderId,
+        folderPath,
+        status: 'present',
+      }),
+    ),
     findPrimaryBookFilesByLibrary: vi.fn().mockResolvedValue([]),
     findBooksByFolderPath: vi.fn().mockResolvedValue([]),
+    findBookFilesByBookId: vi.fn().mockResolvedValue([]),
     findBookFilesByBookIds: vi.fn().mockResolvedValue([]),
+    deleteBookFile: vi.fn().mockResolvedValue(undefined),
     updateBookFolderPath: vi.fn().mockResolvedValue(undefined),
     ...overrides,
   };
@@ -216,7 +234,7 @@ describe('excludePatterns', () => {
         allowedFormats: [],
         formatPriority: DEFAULT_FORMAT_PRIORITY,
         excludePatterns: ['#recycle', '*.bak'],
-        organizationMode: 'auto',
+        organizationMode: 'book_per_folder',
       }),
     });
 
@@ -401,7 +419,7 @@ describe('file identity resolution', () => {
   it('gracefully skips a file that disappears during fingerprinting (ENOENT) — scan still completes', async () => {
     const fileStat = makeFileStat({ ino: 7777 }); // different ino so inode match fails
     mockFindCandidates.mockResolvedValue([makeCandidate('/library/Author/Book', [fileStat])]);
-    mockFingerprint.mockRejectedValueOnce(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+    mockFingerprint.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
 
     const repo = makeRepo();
     const done = awaitScan(repo);
@@ -466,9 +484,12 @@ describe('format priority', () => {
 describe('allowedFormats filtering', () => {
   it('excludes primary files whose format is not in allowedFormats', async () => {
     const repo = makeRepo({
-      findLibrarySettings: vi
-        .fn()
-        .mockResolvedValue({ allowedFormats: ['epub'], formatPriority: DEFAULT_FORMAT_PRIORITY, excludePatterns: [], organizationMode: 'auto' }),
+      findLibrarySettings: vi.fn().mockResolvedValue({
+        allowedFormats: ['epub'],
+        formatPriority: DEFAULT_FORMAT_PRIORITY,
+        excludePatterns: [],
+        organizationMode: 'book_per_folder',
+      }),
     });
 
     // findBookCandidates returns both, but the service filters before processing
@@ -646,7 +667,7 @@ describe('multi-format metadata source routing', () => {
         allowedFormats: [],
         formatPriority: ['m4b', 'epub', 'pdf'],
         excludePatterns: [],
-        organizationMode: 'auto',
+        organizationMode: 'book_per_folder',
       }),
     });
     const m4b = makeFileStat({ absolutePath: '/library/Book/book.m4b', relPath: 'Book/book.m4b', ino: 3001 });
@@ -670,7 +691,7 @@ describe('multi-format metadata source routing', () => {
         allowedFormats: [],
         formatPriority: ['m4b', 'epub', 'pdf'],
         excludePatterns: [],
-        organizationMode: 'auto',
+        organizationMode: 'book_per_folder',
       }),
     });
     const m4b = makeFileStat({ absolutePath: '/library/Book/book.m4b', relPath: 'Book/book.m4b', ino: 3001 });
@@ -757,7 +778,7 @@ describe('multi-format metadata source routing', () => {
         allowedFormats: [],
         formatPriority: ['m4b', 'epub', 'pdf'],
         excludePatterns: [],
-        organizationMode: 'auto',
+        organizationMode: 'book_per_folder',
       }),
     });
     const m4b = makeFileStat({ absolutePath: '/library/Book/book.m4b', relPath: 'Book/book.m4b', ino: 7001 });
@@ -789,7 +810,7 @@ describe('incremental scan — no re-extraction on unchanged winner', () => {
         allowedFormats: [],
         formatPriority: ['m4b', 'epub', 'pdf'],
         excludePatterns: [],
-        organizationMode: 'auto',
+        organizationMode: 'book_per_folder',
       }),
       // m4b already exists in DB — not new; epub is genuinely new
       findBooksByLibraryFolder: vi
@@ -894,6 +915,223 @@ describe('missing book restoration', () => {
   });
 });
 
+describe('cross-library transfer', () => {
+  it('transfers a missing source book into the destination library via inode match', async () => {
+    const destinationFile = makeFileStat({
+      absolutePath: '/dest/Inbox/book.epub',
+      relPath: 'Inbox/book.epub',
+      ino: 4242,
+    });
+    const sourceFile = makeBookFile({
+      id: 500,
+      bookId: 42,
+      libraryFolderId: 10,
+      absolutePath: '/source/Book/book.epub',
+      relPath: 'Book/book.epub',
+      ino: 4242,
+      hash: 'transfer-hash',
+    });
+
+    const repo = makeRepo({
+      findLibraryFolders: vi.fn().mockResolvedValue([{ id: 20, path: '/dest', libraryId: 2 }]),
+      findBooksByLibraryFolder: vi.fn().mockResolvedValue([]),
+      findBookFilesByLibraryFolder: vi.fn().mockResolvedValue([]),
+      findMissingBookFileWithContextByIno: vi.fn().mockResolvedValue({
+        file: sourceFile,
+        libraryId: 1,
+        bookStatus: 'missing',
+        folderPath: '/source/Book',
+        libraryFolderPath: '/source',
+      }),
+      findBookFileWithContextByIno: vi.fn().mockResolvedValue({
+        file: sourceFile,
+        libraryId: 2,
+        bookStatus: 'present',
+        folderPath: '/dest/Inbox',
+        libraryFolderPath: '/source',
+      }),
+    });
+    mockFindCandidates.mockResolvedValue([makeCandidate('/dest/Inbox', [destinationFile])]);
+
+    const done = awaitScan(repo);
+    const { service } = makeService(repo);
+    await service.startScan(2, 'manual');
+    await done;
+
+    expect(repo.moveBookToLibrary).toHaveBeenCalledWith(42, 2, 20, '/dest/Inbox');
+    expect(repo.createBook).not.toHaveBeenCalled();
+    expect(repo.updateBookFile).toHaveBeenCalledWith(
+      500,
+      expect.objectContaining({
+        bookId: 42,
+        libraryFolderId: 20,
+        absolutePath: '/dest/Inbox/book.epub',
+        relPath: 'Inbox/book.epub',
+      }),
+    );
+    expect(repo.updateBookPrimaryFile).toHaveBeenCalledWith(42, 500);
+  });
+
+  it('transfers a source book when inode matches and the previous path no longer exists', async () => {
+    const destinationFile = makeFileStat({
+      absolutePath: '/dest/Inbox/book.epub',
+      relPath: 'Inbox/book.epub',
+      ino: 4343,
+    });
+    const sourceFile = makeBookFile({
+      id: 510,
+      bookId: 55,
+      libraryFolderId: 10,
+      absolutePath: '/source/Book/book.epub',
+      relPath: 'Book/book.epub',
+      ino: 4343,
+      hash: 'transfer-hash',
+    });
+
+    const repo = makeRepo({
+      findLibraryFolders: vi.fn().mockResolvedValue([{ id: 22, path: '/dest', libraryId: 2 }]),
+      findBooksByLibraryFolder: vi.fn().mockResolvedValue([]),
+      findBookFilesByLibraryFolder: vi.fn().mockResolvedValue([]),
+      findMissingBookFileWithContextByIno: vi.fn().mockResolvedValue(null),
+      findBookFileWithContextByIno: vi.fn().mockResolvedValue({
+        file: sourceFile,
+        libraryId: 1,
+        bookStatus: 'present',
+        folderPath: '/source/Book',
+        libraryFolderPath: '/source',
+      }),
+      findMissingBookFileWithContextByHash: vi.fn().mockResolvedValue(null),
+      findBookFileWithContextByHash: vi.fn().mockResolvedValue(null),
+    });
+    mockFindCandidates.mockResolvedValue([makeCandidate('/dest/Inbox', [destinationFile])]);
+    mockStat.mockRejectedValueOnce(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+
+    const done = awaitScan(repo);
+    const { service } = makeService(repo);
+    await service.startScan(2, 'manual');
+    await done;
+
+    expect(repo.moveBookToLibrary).toHaveBeenCalledWith(55, 2, 22, '/dest/Inbox');
+    expect(repo.createBook).not.toHaveBeenCalled();
+    expect(repo.updateBookFile).toHaveBeenCalledWith(
+      510,
+      expect.objectContaining({
+        bookId: 55,
+        libraryFolderId: 22,
+        absolutePath: '/dest/Inbox/book.epub',
+        relPath: 'Inbox/book.epub',
+      }),
+    );
+    expect(repo.updateBookPrimaryFile).toHaveBeenCalledWith(55, 510);
+  });
+
+  it('transfers a missing source book via hash fallback when inode differs', async () => {
+    const destinationFile = makeFileStat({
+      absolutePath: '/dest/Inbox/book.epub',
+      relPath: 'Inbox/book.epub',
+      ino: 9999,
+    });
+    const sourceFile = makeBookFile({
+      id: 600,
+      bookId: 77,
+      libraryFolderId: 11,
+      absolutePath: '/source/Book/book.epub',
+      relPath: 'Book/book.epub',
+      ino: 2222,
+      hash: 'transfer-hash',
+    });
+
+    const repo = makeRepo({
+      findLibraryFolders: vi.fn().mockResolvedValue([{ id: 21, path: '/dest', libraryId: 3 }]),
+      findBooksByLibraryFolder: vi.fn().mockResolvedValue([]),
+      findBookFilesByLibraryFolder: vi.fn().mockResolvedValue([]),
+      findMissingBookFileWithContextByIno: vi.fn().mockResolvedValue(null),
+      findMissingBookFileWithContextByHash: vi.fn().mockResolvedValue({
+        file: sourceFile,
+        libraryId: 1,
+        bookStatus: 'missing',
+        folderPath: '/source/Book',
+        libraryFolderPath: '/source',
+      }),
+      findBookFileWithContextByIno: vi.fn().mockResolvedValue(null),
+      findBookFileWithContextByHash: vi.fn().mockResolvedValue({
+        file: sourceFile,
+        libraryId: 3,
+        bookStatus: 'present',
+        folderPath: '/dest/Inbox',
+        libraryFolderPath: '/source',
+      }),
+      findBookFileByHash: vi.fn().mockResolvedValue(null),
+    });
+    mockFindCandidates.mockResolvedValue([makeCandidate('/dest/Inbox', [destinationFile])]);
+    mockFingerprint.mockResolvedValue('transfer-hash');
+
+    const done = awaitScan(repo);
+    const { service } = makeService(repo);
+    await service.startScan(3, 'manual');
+    await done;
+
+    expect(repo.moveBookToLibrary).toHaveBeenCalledWith(77, 3, 21, '/dest/Inbox');
+    expect(repo.createBook).not.toHaveBeenCalled();
+    expect(repo.updateBookFile).toHaveBeenCalledWith(
+      600,
+      expect.objectContaining({
+        bookId: 77,
+        libraryFolderId: 21,
+        absolutePath: '/dest/Inbox/book.epub',
+      }),
+    );
+    expect(repo.updateBookPrimaryFile).toHaveBeenCalledWith(77, 600);
+  });
+
+  it('does not transfer ownership when destination folder already has a book', async () => {
+    const destinationFile = makeFileStat({
+      absolutePath: '/dest/Inbox/book.epub',
+      relPath: 'Inbox/book.epub',
+      ino: 5151,
+    });
+    const sourceFile = makeBookFile({
+      id: 700,
+      bookId: 88,
+      libraryFolderId: 12,
+      absolutePath: '/source/Book/book.epub',
+      relPath: 'Book/book.epub',
+      ino: 5151,
+      hash: 'transfer-hash',
+    });
+    const repo = makeRepo({
+      findLibraryFolders: vi.fn().mockResolvedValue([{ id: 30, path: '/dest', libraryId: 4 }]),
+      findBooksByLibraryFolder: vi
+        .fn()
+        .mockResolvedValue([{ id: 9, libraryId: 4, libraryFolderId: 30, folderPath: '/dest/Inbox', status: 'present' }]),
+      findBookFilesByLibraryFolder: vi.fn().mockResolvedValue([]),
+      findMissingBookFileWithContextByIno: vi.fn().mockResolvedValue({
+        file: sourceFile,
+        libraryId: 1,
+        bookStatus: 'missing',
+        folderPath: '/source/Book',
+        libraryFolderPath: '/source',
+      }),
+      findBookFileWithContextByIno: vi.fn().mockResolvedValue({
+        file: sourceFile,
+        libraryId: 1,
+        bookStatus: 'missing',
+        folderPath: '/source/Book',
+        libraryFolderPath: '/source',
+      }),
+    });
+    mockFindCandidates.mockResolvedValue([makeCandidate('/dest/Inbox', [destinationFile])]);
+
+    const done = awaitScan(repo);
+    const { service } = makeService(repo);
+    await service.startScan(4, 'manual');
+    await done;
+
+    expect(repo.moveBookToLibrary).not.toHaveBeenCalled();
+    expect(repo.createBook).not.toHaveBeenCalled();
+  });
+});
+
 // ── Virtual sibling drain / merge ────────────────────────────────────────────
 
 describe('virtual sibling drain', () => {
@@ -1162,7 +1400,7 @@ describe('book_per_file mode — runScan', () => {
     expect(mockFindCandidates).not.toHaveBeenCalled();
   });
 
-  it('calls findBookCandidates (not loose) when organizationMode is auto', async () => {
+  it('calls findBookCandidates (not loose) when organizationMode is book_per_folder', async () => {
     const repo = makeRepo();
     const done = awaitScan(repo);
     const { service } = makeService(repo);
@@ -1323,7 +1561,7 @@ describe('book_per_file mode — scanBookFolder', () => {
     expect(repo.createBook).not.toHaveBeenCalled();
   });
 
-  it('falls through to normal folder scan when mode is auto', async () => {
+  it('falls through to normal folder scan when mode is book_per_folder', async () => {
     const repo = makeRepo({
       findLibraryFolders: vi.fn().mockResolvedValue([{ id: 1, path: '/library', libraryId: 1 }]),
     });
diff --git a/server/src/modules/scanner/scanner.service.ts b/server/src/modules/scanner/scanner.service.ts
index 579af09b0..06c35145d 100644
--- a/server/src/modules/scanner/scanner.service.ts
+++ b/server/src/modules/scanner/scanner.service.ts
@@ -16,6 +16,7 @@ import { ScannerRepository } from './scanner.repository';
 
 const METADATA_FORMATS = new Set(['epub', 'mobi', 'azw3', 'azw', 'cbz', 'cbr', 'cb7', 'fb2', 'pdf', 'm4b', 'mp3', 'm4a', 'opus', 'ogg', 'flac']);
 const BATCH_SIZE = 5;
+type OrganizationMode = 'book_per_file' | 'book_per_folder';
 
 interface ScanCounts {
   addedCount: number;
@@ -23,6 +24,10 @@ interface ScanCounts {
   missingCount: number;
 }
 
+function normalizeOrganizationMode(mode: string | null | undefined): OrganizationMode {
+  return mode === 'book_per_file' ? 'book_per_file' : 'book_per_folder';
+}
+
 @Injectable()
 export class ScannerService implements OnApplicationBootstrap {
   private readonly logger = new Logger(ScannerService.name);
@@ -57,7 +62,7 @@ export class ScannerService implements OnApplicationBootstrap {
       const allowedFormats = settings?.allowedFormats ?? [];
       const formatPriority = settings?.formatPriority ?? DEFAULT_FORMAT_PRIORITY;
       const excludePatterns = settings?.excludePatterns ?? [];
-      const organizationMode = settings?.organizationMode ?? 'auto';
+      const organizationMode = normalizeOrganizationMode(settings?.organizationMode);
 
       const job = await this.scannerRepo.createScanJob(libraryId, triggeredBy);
 
@@ -147,6 +152,10 @@ export class ScannerService implements OnApplicationBootstrap {
     );
   }
 
+  isScanRunning(libraryId: number): boolean {
+    return this.scanJobStore.isRunning(libraryId);
+  }
+
   scanBookFolderAsync(filePath: string, libraryId: number): void {
     this.scanBookFolder(filePath, libraryId).catch((err) =>
       this.logger.error(
@@ -159,6 +168,12 @@ export class ScannerService implements OnApplicationBootstrap {
     const event = 'scanner.scan_book_folder';
     const startedAt = Date.now();
     this.logger.log(`[${event}] [start] libraryId=${libraryId} filePath="${filePath.replace(/"/g, '\\"')}" - targeted folder scan started`);
+    if (this.scanJobStore.isRunning(libraryId)) {
+      this.logger.log(
+        `[${event}] [end] libraryId=${libraryId} filePath="${filePath.replace(/"/g, '\\"')}" durationMs=${Date.now() - startedAt} skippedDueToRunningFullScan=true - targeted folder scan completed`,
+      );
+      return;
+    }
     const allFolders = await this.scannerRepo.findLibraryFolders(libraryId);
     const libraryFolder = allFolders.find((f) => filePath.startsWith(f.path + sep));
     if (!libraryFolder) {
@@ -172,7 +187,7 @@ export class ScannerService implements OnApplicationBootstrap {
     const allowedFormats = settings?.allowedFormats ?? [];
     const formatPriority = settings?.formatPriority ?? DEFAULT_FORMAT_PRIORITY;
     const excludePatterns = settings?.excludePatterns ?? [];
-    const organizationMode = settings?.organizationMode ?? 'auto';
+    const organizationMode = normalizeOrganizationMode(settings?.organizationMode);
 
     // In book_per_file mode each file is its own book — skip folder resolution entirely
     // and build a single-file candidate directly from the changed file.
@@ -214,7 +229,7 @@ export class ScannerService implements OnApplicationBootstrap {
         ],
       };
 
-      const knownBooks = await this.scannerRepo.findBooksByFolderPath(filePath);
+      const knownBooks = await this.scannerRepo.findBooksByFolderPath(filePath, libraryId);
       const knownFiles = await this.scannerRepo.findBookFilesByBookIds(knownBooks.map((b) => b.id));
 
       const bookByFolderPath = new Map<string, { id: number; status: string; folderPath: string }>(
@@ -305,7 +320,7 @@ export class ScannerService implements OnApplicationBootstrap {
 
     // Load only books/files relevant to this specific folder (including any
     // virtual stem-split children so the merge logic in upsertBook can run).
-    const knownBooks = await this.scannerRepo.findBooksByFolderPath(resolvedBookFolder);
+    const knownBooks = await this.scannerRepo.findBooksByFolderPath(resolvedBookFolder, libraryId);
     const knownFiles = await this.scannerRepo.findBookFilesByBookIds(knownBooks.map((b) => b.id));
 
     const bookByFolderPath = new Map<string, { id: number; status: string; folderPath: string }>(
@@ -333,7 +348,7 @@ export class ScannerService implements OnApplicationBootstrap {
     allowedFormats: string[],
     formatPriority: string[],
     excludePatterns: string[],
-    organizationMode: string,
+    organizationMode: OrganizationMode,
   ): Promise<void> {
     const event = 'scanner.run_scan';
     const startedAt = Date.now();
@@ -510,6 +525,7 @@ export class ScannerService implements OnApplicationBootstrap {
   ): Promise<{ bookId: number; added: number; updated: number }> {
     const counts = { added: 0, updated: 0 };
     const fileCounts: ScanCounts = { addedCount: 0, updatedCount: 0, missingCount: 0 };
+    const retainedFileIds = new Set<number>();
 
     const book = await this.upsertBook(candidate, libraryId, libraryFolderId, bookByFolderPath, fileCounts);
     counts.added += fileCounts.addedCount;
@@ -562,9 +578,12 @@ export class ScannerService implements OnApplicationBootstrap {
           isNew: processResult.isNew,
           wasReassigned: processResult.reassigned,
         });
+        retainedFileIds.add(processResult.fileId);
       }
     }
 
+    await this.pruneMissingBookFiles(book.id, retainedFileIds, fileByPath, fileByIno, counts);
+
     // ── Phase 2: Pick winner (primary file) from all registered content files. ──
     const contentFiles = registeredFiles.filter((f) => f.role === 'content');
 
@@ -677,6 +696,9 @@ export class ScannerService implements OnApplicationBootstrap {
         return { ...survivor, folderPath: candidate.folderPath };
       }
 
+      const transferred = await this.tryTransferMissingBook(candidate, libraryId, libraryFolderId, bookByFolderPath, counts);
+      if (transferred) return transferred;
+
       const book = await this.scannerRepo.createBook({
         libraryId,
         libraryFolderId,
@@ -691,6 +713,7 @@ export class ScannerService implements OnApplicationBootstrap {
             `[scanner.upsert_book] [fail] libraryId=${libraryId} bookId=${book.id} action=schedule_metadata_fetch errorClass=${err.name} error="${err.message.replace(/"/g, '\\"')}" - metadata fetch schedule failed`,
           ),
         );
+      bookByFolderPath.set(candidate.folderPath, { id: book.id, status: book.status, folderPath: book.folderPath });
       return book;
     }
 
@@ -717,6 +740,81 @@ export class ScannerService implements OnApplicationBootstrap {
     return existing;
   }
 
+  private async tryTransferMissingBook(
+    candidate: BookCandidate,
+    libraryId: number,
+    libraryFolderId: number,
+    bookByFolderPath: Map<string, { id: number; status: string; folderPath: string }>,
+    counts: ScanCounts,
+  ): Promise<{ id: number; status: string; folderPath: string } | null> {
+    const contentFiles = candidate.files.filter((file) => {
+      const { role } = classifyFile(file.absolutePath);
+      return role === 'content' && file.sizeBytes > 0;
+    });
+    if (contentFiles.length === 0) return null;
+
+    let sourceBookId: number | null = null;
+
+    for (const file of contentFiles) {
+      const byIno = await this.scannerRepo.findMissingBookFileWithContextByIno(file.ino);
+      if (!byIno) continue;
+      sourceBookId = byIno.file.bookId;
+      break;
+    }
+
+    if (sourceBookId == null) {
+      for (const file of contentFiles) {
+        const byIno = await this.scannerRepo.findBookFileWithContextByIno(file.ino);
+        if (!byIno || byIno.file.absolutePath === file.absolutePath) continue;
+        if (byIno.libraryId === libraryId) continue;
+        const previousPathStat = await stat(byIno.file.absolutePath).catch(() => null);
+        if (previousPathStat?.isFile()) continue;
+        sourceBookId = byIno.file.bookId;
+        break;
+      }
+    }
+
+    if (sourceBookId == null) {
+      for (const file of contentFiles) {
+        let hash: string;
+        try {
+          hash = await fingerprintFile(file.absolutePath);
+        } catch (err) {
+          const code = (err as NodeJS.ErrnoException).code;
+          if (code === 'ENOENT' || code === 'EACCES') continue;
+          throw err;
+        }
+
+        const byHash = await this.scannerRepo.findMissingBookFileWithContextByHash(hash);
+        if (byHash) {
+          sourceBookId = byHash.file.bookId;
+          break;
+        }
+
+        const byHashAny = await this.scannerRepo.findBookFileWithContextByHash(hash);
+        if (!byHashAny || byHashAny.file.absolutePath === file.absolutePath) continue;
+        if (byHashAny.libraryId === libraryId) continue;
+        const previousPathStat = await stat(byHashAny.file.absolutePath).catch(() => null);
+        if (previousPathStat?.isFile()) continue;
+        sourceBookId = byHashAny.file.bookId;
+        break;
+      }
+    }
+
+    if (sourceBookId == null) return null;
+
+    const moved = await this.scannerRepo.moveBookToLibrary(sourceBookId, libraryId, libraryFolderId, candidate.folderPath);
+    if (!moved) return null;
+
+    counts.updatedCount++;
+    const transferred = { id: moved.id, status: moved.status, folderPath: moved.folderPath };
+    bookByFolderPath.set(candidate.folderPath, transferred);
+    this.logger.log(
+      `[scanner.upsert_book] [end] libraryId=${libraryId} bookId=${moved.id} folder="${candidate.folderPath.replace(/"/g, '\\"')}" action=transfer_missing_book - missing book transferred into destination library`,
+    );
+    return transferred;
+  }
+
   private async processFile(
     fileStat: FileStat,
     format: string | null,
@@ -738,6 +836,7 @@ export class ScannerService implements OnApplicationBootstrap {
       if (changed || reassigned) {
         await this.scannerRepo.updateBookFile(byPath.id, {
           ...(reassigned && { bookId }),
+          libraryFolderId,
           ino: fileStat.ino,
           sizeBytes: fileStat.sizeBytes,
           mtime: fileStat.mtime,
@@ -750,14 +849,31 @@ export class ScannerService implements OnApplicationBootstrap {
         // Always keep sort order current even when content is unchanged.
         await this.scannerRepo.updateBookFile(byPath.id, { sortOrder });
       }
+      if (byPath.ino !== fileStat.ino) {
+        const previousIno = fileByIno.get(byPath.ino);
+        if (previousIno?.id === byPath.id) {
+          fileByIno.delete(byPath.ino);
+        }
+      }
+      fileByPath.set(fileStat.absolutePath, {
+        id: byPath.id,
+        bookId,
+        ino: fileStat.ino,
+        sizeBytes: fileStat.sizeBytes,
+        mtime: fileStat.mtime,
+        hash: byPath.hash,
+      });
+      fileByIno.set(fileStat.ino, { id: byPath.id, bookId, absolutePath: fileStat.absolutePath });
       return { isNew: false, reassigned: reassigned, fileId: byPath.id };
     }
 
     // 2. Inode match — renamed/moved within the same filesystem.
     const byIno = fileByIno.get(fileStat.ino);
     if (byIno) {
+      const oldAbsolutePath = byIno.absolutePath;
       await this.scannerRepo.updateBookFile(byIno.id, {
         bookId,
+        libraryFolderId,
         absolutePath: fileStat.absolutePath,
         relPath: fileStat.relPath,
         sizeBytes: fileStat.sizeBytes,
@@ -767,10 +883,72 @@ export class ScannerService implements OnApplicationBootstrap {
         sortOrder,
       });
       counts.updatedCount++;
+      const oldPathEntry = fileByPath.get(oldAbsolutePath);
+      if (oldPathEntry?.id === byIno.id) {
+        fileByPath.delete(oldAbsolutePath);
+      }
+      fileByPath.set(fileStat.absolutePath, {
+        id: byIno.id,
+        bookId,
+        ino: fileStat.ino,
+        sizeBytes: fileStat.sizeBytes,
+        mtime: fileStat.mtime,
+        hash: oldPathEntry?.hash ?? null,
+      });
+      fileByIno.set(fileStat.ino, { id: byIno.id, bookId, absolutePath: fileStat.absolutePath });
       return { isNew: false, reassigned: byIno.bookId !== bookId, fileId: byIno.id };
     }
 
-    // 3. Hash match — cross-filesystem copy (expensive, last resort).
+    // 3. Global inode match — cross-library move / rescan reconciliation.
+    let globalByIno = await this.scannerRepo.findBookFileWithContextByIno(fileStat.ino);
+    if (
+      !globalByIno ||
+      globalByIno.file.absolutePath === fileStat.absolutePath ||
+      (globalByIno.file.bookId !== bookId && globalByIno.bookStatus !== 'missing')
+    ) {
+      globalByIno = await this.scannerRepo.findMissingBookFileWithContextByIno(fileStat.ino);
+    }
+
+    if (
+      globalByIno &&
+      globalByIno.file.absolutePath !== fileStat.absolutePath &&
+      (globalByIno.file.bookId === bookId || globalByIno.bookStatus === 'missing')
+    ) {
+      const oldAbsolutePath = globalByIno.file.absolutePath;
+      await this.scannerRepo.updateBookFile(globalByIno.file.id, {
+        bookId,
+        libraryFolderId,
+        absolutePath: fileStat.absolutePath,
+        relPath: fileStat.relPath,
+        ino: fileStat.ino,
+        sizeBytes: fileStat.sizeBytes,
+        mtime: fileStat.mtime,
+        format,
+        role,
+        sortOrder,
+      });
+      counts.updatedCount++;
+      const oldPathEntry = fileByPath.get(oldAbsolutePath);
+      if (oldPathEntry?.id === globalByIno.file.id) {
+        fileByPath.delete(oldAbsolutePath);
+      }
+      const oldInoEntry = fileByIno.get(globalByIno.file.ino);
+      if (oldInoEntry?.id === globalByIno.file.id) {
+        fileByIno.delete(globalByIno.file.ino);
+      }
+      fileByPath.set(fileStat.absolutePath, {
+        id: globalByIno.file.id,
+        bookId,
+        ino: fileStat.ino,
+        sizeBytes: fileStat.sizeBytes,
+        mtime: fileStat.mtime,
+        hash: globalByIno.file.hash,
+      });
+      fileByIno.set(fileStat.ino, { id: globalByIno.file.id, bookId, absolutePath: fileStat.absolutePath });
+      return { isNew: false, reassigned: globalByIno.file.bookId !== bookId, fileId: globalByIno.file.id };
+    }
+
+    // 4. Hash match — cross-filesystem copy (expensive, last resort).
     let hash: string;
     try {
       hash = await fingerprintFile(fileStat.absolutePath);
@@ -786,8 +964,10 @@ export class ScannerService implements OnApplicationBootstrap {
     }
     const byHash = await this.scannerRepo.findBookFileByHash(hash, libraryFolderId);
     if (byHash) {
+      const oldAbsolutePath = byHash.absolutePath;
       await this.scannerRepo.updateBookFile(byHash.id, {
         bookId,
+        libraryFolderId,
         absolutePath: fileStat.absolutePath,
         relPath: fileStat.relPath,
         ino: fileStat.ino,
@@ -798,10 +978,76 @@ export class ScannerService implements OnApplicationBootstrap {
         sortOrder,
       });
       counts.updatedCount++;
+      const oldPathEntry = fileByPath.get(oldAbsolutePath);
+      if (oldPathEntry?.id === byHash.id) {
+        fileByPath.delete(oldAbsolutePath);
+      }
+      const oldInoEntry = fileByIno.get(byHash.ino);
+      if (oldInoEntry?.id === byHash.id) {
+        fileByIno.delete(byHash.ino);
+      }
+      fileByPath.set(fileStat.absolutePath, {
+        id: byHash.id,
+        bookId,
+        ino: fileStat.ino,
+        sizeBytes: fileStat.sizeBytes,
+        mtime: fileStat.mtime,
+        hash: byHash.hash,
+      });
+      fileByIno.set(fileStat.ino, { id: byHash.id, bookId, absolutePath: fileStat.absolutePath });
       return { isNew: false, reassigned: byHash.bookId !== bookId, fileId: byHash.id };
     }
 
-    // 4. Genuinely new file.
+    let globalByHash = await this.scannerRepo.findBookFileWithContextByHash(hash);
+    if (
+      !globalByHash ||
+      globalByHash.file.absolutePath === fileStat.absolutePath ||
+      (globalByHash.file.bookId !== bookId && globalByHash.bookStatus !== 'missing')
+    ) {
+      globalByHash = await this.scannerRepo.findMissingBookFileWithContextByHash(hash);
+    }
+
+    if (
+      globalByHash &&
+      globalByHash.file.absolutePath !== fileStat.absolutePath &&
+      (globalByHash.file.bookId === bookId || globalByHash.bookStatus === 'missing')
+    ) {
+      const oldAbsolutePath = globalByHash.file.absolutePath;
+      await this.scannerRepo.updateBookFile(globalByHash.file.id, {
+        bookId,
+        libraryFolderId,
+        absolutePath: fileStat.absolutePath,
+        relPath: fileStat.relPath,
+        ino: fileStat.ino,
+        sizeBytes: fileStat.sizeBytes,
+        mtime: fileStat.mtime,
+        hash,
+        format,
+        role,
+        sortOrder,
+      });
+      counts.updatedCount++;
+      const oldPathEntry = fileByPath.get(oldAbsolutePath);
+      if (oldPathEntry?.id === globalByHash.file.id) {
+        fileByPath.delete(oldAbsolutePath);
+      }
+      const oldInoEntry = fileByIno.get(globalByHash.file.ino);
+      if (oldInoEntry?.id === globalByHash.file.id) {
+        fileByIno.delete(globalByHash.file.ino);
+      }
+      fileByPath.set(fileStat.absolutePath, {
+        id: globalByHash.file.id,
+        bookId,
+        ino: fileStat.ino,
+        sizeBytes: fileStat.sizeBytes,
+        mtime: fileStat.mtime,
+        hash,
+      });
+      fileByIno.set(fileStat.ino, { id: globalByHash.file.id, bookId, absolutePath: fileStat.absolutePath });
+      return { isNew: false, reassigned: globalByHash.file.bookId !== bookId, fileId: globalByHash.file.id };
+    }
+
+    // 5. Genuinely new file.
     const created = await this.scannerRepo.createBookFile({
       bookId,
       libraryFolderId,
@@ -816,9 +1062,44 @@ export class ScannerService implements OnApplicationBootstrap {
       sortOrder,
     });
     counts.addedCount++;
+    fileByPath.set(fileStat.absolutePath, {
+      id: created.id,
+      bookId,
+      ino: fileStat.ino,
+      sizeBytes: fileStat.sizeBytes,
+      mtime: fileStat.mtime,
+      hash,
+    });
+    fileByIno.set(fileStat.ino, { id: created.id, bookId, absolutePath: fileStat.absolutePath });
     return { isNew: true, reassigned: false, fileId: created.id };
   }
 
+  private async pruneMissingBookFiles(
+    bookId: number,
+    retainedFileIds: Set<number>,
+    fileByPath: Map<string, { id: number; bookId: number; ino: number; sizeBytes: number | null; mtime: Date | null; hash: string | null }>,
+    fileByIno: Map<number, { id: number; bookId: number; absolutePath: string }>,
+    counts: { added: number; updated: number },
+  ): Promise<void> {
+    const existingFiles = await this.scannerRepo.findBookFilesByBookId(bookId);
+
+    for (const existing of existingFiles) {
+      if (retainedFileIds.has(existing.id)) continue;
+
+      await this.scannerRepo.deleteBookFile(existing.id);
+      counts.updated += 1;
+
+      const byPathEntry = fileByPath.get(existing.absolutePath);
+      if (byPathEntry?.id === existing.id) {
+        fileByPath.delete(existing.absolutePath);
+      }
+      const byInoEntry = fileByIno.get(existing.ino);
+      if (byInoEntry?.id === existing.id) {
+        fileByIno.delete(existing.ino);
+      }
+    }
+  }
+
   private emitFromStore(libraryId: number, jobId: number, status: 'running' | 'completed' | 'failed', errorMessage?: string): void {
     const entry = this.scanJobStore.get(libraryId);
     const event: ScanProgressEvent = {
diff --git a/server/src/scripts/db-prepare-e2e.ts b/server/src/scripts/db-prepare-e2e.ts
new file mode 100644
index 000000000..91c0188c7
--- /dev/null
+++ b/server/src/scripts/db-prepare-e2e.ts
@@ -0,0 +1,103 @@
+import { Client } from 'pg';
+
+const DEFAULT_E2E_DATABASE_URL = 'postgres://projectx:projectx@localhost:5432/projectx_e2e';
+const CONNECT_RETRY_ATTEMPTS = 30;
+const CONNECT_RETRY_DELAY_MS = 1000;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function escapeIdentifier(identifier: string): string {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+
+function resolveTargetDatabaseUrl(): URL {
+  const connectionString = process.env.DATABASE_URL ?? process.env.E2E_DATABASE_URL ?? DEFAULT_E2E_DATABASE_URL;
+  return new URL(connectionString);
+}
+
+function parseDatabaseName(url: URL): string {
+  const databaseName = decodeURIComponent(url.pathname.replace(/^\//, ''));
+  if (!databaseName) {
+    throw new Error('E2E database URL must include a database name');
+  }
+  return databaseName;
+}
+
+function assertSafeDatabaseName(databaseName: string): void {
+  if (!databaseName.endsWith('_e2e')) {
+    throw new Error(`Refusing to reset non-e2e database "${databaseName}"`);
+  }
+  if (!/^[A-Za-z0-9_]+$/.test(databaseName)) {
+    throw new Error(`Unsupported database name "${databaseName}". Use only letters, numbers, and underscores.`);
+  }
+}
+
+async function connectWithRetry(connectionString: string, label: string): Promise<Client> {
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= CONNECT_RETRY_ATTEMPTS; attempt++) {
+    const client = new Client({ connectionString });
+    try {
+      await client.connect();
+      return client;
+    } catch (err) {
+      lastError = err;
+      await client.end().catch(() => undefined);
+      if (attempt < CONNECT_RETRY_ATTEMPTS) {
+        await sleep(CONNECT_RETRY_DELAY_MS);
+      }
+    }
+  }
+
+  throw new Error(
+    `Could not connect to ${label} after ${CONNECT_RETRY_ATTEMPTS} attempts: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
+  );
+}
+
+async function createDatabaseIfMissing(adminClient: Client, databaseName: string): Promise<void> {
+  const existing = await adminClient.query('SELECT 1 FROM pg_database WHERE datname = $1 LIMIT 1', [databaseName]);
+  if (existing.rowCount && existing.rowCount > 0) return;
+  await adminClient.query(`CREATE DATABASE ${escapeIdentifier(databaseName)}`);
+}
+
+async function resetE2EDatabase(targetClient: Client): Promise<void> {
+  await targetClient.query('DROP SCHEMA IF EXISTS public CASCADE');
+  await targetClient.query('CREATE SCHEMA public');
+  await targetClient.query('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"');
+  await targetClient.query('CREATE EXTENSION IF NOT EXISTS pg_trgm');
+  await targetClient.query('CREATE EXTENSION IF NOT EXISTS vector');
+  await targetClient.query('CREATE SCHEMA IF NOT EXISTS drizzle');
+  await targetClient.query('CREATE TABLE IF NOT EXISTS drizzle.__drizzle_migrations (id serial PRIMARY KEY, hash text NOT NULL, created_at bigint)');
+  await targetClient.query('DELETE FROM drizzle.__drizzle_migrations');
+}
+
+async function run(): Promise<void> {
+  const targetUrl = resolveTargetDatabaseUrl();
+  const databaseName = parseDatabaseName(targetUrl);
+  assertSafeDatabaseName(databaseName);
+
+  const adminUrl = new URL(targetUrl.toString());
+  adminUrl.pathname = '/postgres';
+  adminUrl.search = '';
+  adminUrl.hash = '';
+
+  const adminClient = await connectWithRetry(adminUrl.toString(), 'PostgreSQL admin database');
+  try {
+    await createDatabaseIfMissing(adminClient, databaseName);
+  } finally {
+    await adminClient.end();
+  }
+
+  const targetClient = await connectWithRetry(targetUrl.toString(), `PostgreSQL database "${databaseName}"`);
+  try {
+    await resetE2EDatabase(targetClient);
+  } finally {
+    await targetClient.end();
+  }
+
+  console.log(`Prepared e2e database: ${databaseName}`);
+}
+
+void run();
diff --git a/server/test/e2e/scanner-fixture-builder.ts b/server/test/e2e/scanner-fixture-builder.ts
new file mode 100644
index 000000000..590e3e280
--- /dev/null
+++ b/server/test/e2e/scanner-fixture-builder.ts
@@ -0,0 +1,48 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { dirname, join } from 'path';
+
+export type FixtureEntry = { kind: 'file'; path: string; content?: string } | { kind: 'dir'; path: string };
+
+export interface FixtureTree {
+  rootPath: string;
+  cleanup: () => Promise<void>;
+}
+
+function assertRelativePath(path: string): void {
+  if (path.startsWith('/')) {
+    throw new Error(`Fixture paths must be relative. Received "${path}"`);
+  }
+}
+
+export function file(path: string, content?: string): FixtureEntry {
+  assertRelativePath(path);
+  return { kind: 'file', path, content: content ?? `${path}\n`.repeat(600) };
+}
+
+export function dir(path: string): FixtureEntry {
+  assertRelativePath(path);
+  return { kind: 'dir', path };
+}
+
+export async function createFixtureTree(entries: FixtureEntry[], prefix = 'scanner-e2e-'): Promise<FixtureTree> {
+  const rootPath = await mkdtemp(join(tmpdir(), prefix));
+
+  for (const entry of entries) {
+    const fullPath = join(rootPath, entry.path);
+    if (entry.kind === 'dir') {
+      await mkdir(fullPath, { recursive: true });
+      continue;
+    }
+
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, entry.content);
+  }
+
+  return {
+    rootPath,
+    cleanup: async () => {
+      await rm(rootPath, { recursive: true, force: true });
+    },
+  };
+}
diff --git a/server/test/e2e/scanner-harness.ts b/server/test/e2e/scanner-harness.ts
new file mode 100644
index 000000000..8bbdf56bf
--- /dev/null
+++ b/server/test/e2e/scanner-harness.ts
@@ -0,0 +1,235 @@
+import { randomUUID } from 'crypto';
+import fastifyCookie from '@fastify/cookie';
+import { eq } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import { Test } from '@nestjs/testing';
+import { DEFAULT_FORMAT_PRIORITY } from '@projectx/types';
+
+import { AppModule } from '../../src/app.module';
+import { DB } from '../../src/db';
+import * as schema from '../../src/db/schema';
+import { bookFiles, books, libraries, libraryFolders, scanJobs } from '../../src/db/schema';
+import { MetadataService } from '../../src/modules/metadata/metadata.service';
+import { FileWatcherService } from '../../src/modules/scanner/file-watcher.service';
+
+type Db = NodePgDatabase<typeof schema>;
+type OrganizationMode = 'book_per_file' | 'book_per_folder';
+
+const ADMIN_SETUP_DTO = {
+  username: 'scanner-e2e-admin',
+  name: 'Scanner E2E Admin',
+  email: 'scanner-e2e-admin@example.com',
+  password: 'ScannerE2E123',
+};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeMetadataNoopMock(): Pick<
+  MetadataService,
+  'extractAndSave' | 'refreshCoverForBook' | 'extractAudioFileDuration' | 'aggregateAudioDuration' | 'extractAudioChaptersAndNarrators'
+> {
+  return {
+    extractAndSave: () => Promise.resolve(undefined),
+    refreshCoverForBook: () => Promise.resolve(false),
+    extractAudioFileDuration: () => Promise.resolve(undefined),
+    aggregateAudioDuration: () => Promise.resolve(undefined),
+    extractAudioChaptersAndNarrators: () => Promise.resolve(undefined),
+  };
+}
+
+async function getAdminToken(app: NestFastifyApplication): Promise<string> {
+  const setupResponse = await app.inject({
+    method: 'POST',
+    url: '/api/v1/auth/setup',
+    payload: ADMIN_SETUP_DTO,
+  });
+
+  if (setupResponse.statusCode === 201) {
+    const body = setupResponse.json() as { accessToken?: string };
+    if (!body.accessToken) throw new Error('Setup succeeded but accessToken was missing');
+    return body.accessToken;
+  }
+
+  if (setupResponse.statusCode === 409) {
+    throw new Error('Initial setup already completed. Use the dedicated e2e database reset command before running scanner e2e tests.');
+  }
+
+  throw new Error(`Unexpected setup response: ${setupResponse.statusCode} ${setupResponse.body}`);
+}
+
+export interface ScannerE2EContext {
+  app: NestFastifyApplication;
+  db: Db;
+  adminToken: string;
+}
+
+export async function createScannerE2EContext(): Promise<ScannerE2EContext> {
+  const moduleFixture = await Test.createTestingModule({
+    imports: [AppModule],
+  })
+    .overrideProvider(MetadataService)
+    .useValue(makeMetadataNoopMock())
+    .compile();
+
+  const app = moduleFixture.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+  app.setGlobalPrefix('api/v1');
+  await app.register(fastifyCookie as never);
+  await app.init();
+  await app.getHttpAdapter().getInstance().ready();
+
+  const db = app.get<Db>(DB);
+  const adminToken = await getAdminToken(app);
+  return { app, db, adminToken };
+}
+
+export async function closeScannerE2EContext(ctx: ScannerE2EContext): Promise<void> {
+  await ctx.app.close();
+}
+
+export interface SeedLibraryInput {
+  rootPath: string;
+  mode: OrganizationMode;
+  allowedFormats?: string[];
+  excludePatterns?: string[];
+  watch?: boolean;
+  name?: string;
+}
+
+export async function seedLibrary(db: Db, input: SeedLibraryInput): Promise<{ libraryId: number; libraryFolderId: number }> {
+  const [library] = await db
+    .insert(libraries)
+    .values({
+      name: input.name ?? `scanner-e2e-${input.mode}-${randomUUID()}`,
+      watch: input.watch ?? false,
+      organizationMode: input.mode,
+      allowedFormats: input.allowedFormats ?? [],
+      excludePatterns: input.excludePatterns ?? [],
+      formatPriority: [...DEFAULT_FORMAT_PRIORITY],
+    })
+    .returning({ id: libraries.id });
+
+  const [libraryFolder] = await db
+    .insert(libraryFolders)
+    .values({
+      libraryId: library.id,
+      path: input.rootPath,
+    })
+    .returning({ id: libraryFolders.id });
+
+  return { libraryId: library.id, libraryFolderId: libraryFolder.id };
+}
+
+export async function triggerLibraryScan(ctx: ScannerE2EContext, libraryId: number): Promise<number> {
+  const response = await ctx.app.inject({
+    method: 'POST',
+    url: `/api/v1/scanner/libraries/${libraryId}/scan`,
+    headers: { authorization: `Bearer ${ctx.adminToken}` },
+  });
+
+  if (response.statusCode !== 202) {
+    throw new Error(`Scan endpoint failed: ${response.statusCode} ${response.body}`);
+  }
+
+  const body = response.json() as { jobId?: number };
+  if (!body.jobId) {
+    throw new Error(`Scan endpoint returned no jobId: ${response.body}`);
+  }
+  return body.jobId;
+}
+
+export async function triggerAndWaitForLibraryScan(
+  ctx: ScannerE2EContext,
+  libraryId: number,
+  timeoutMs = 30_000,
+): Promise<typeof scanJobs.$inferSelect> {
+  const jobId = await triggerLibraryScan(ctx, libraryId);
+  return waitForScanCompletion(ctx.db, jobId, timeoutMs);
+}
+
+export async function startLibraryWatcher(ctx: ScannerE2EContext, libraryId: number, paths: string[]): Promise<void> {
+  const watcher = ctx.app.get(FileWatcherService);
+  await watcher.startWatcher(libraryId, paths);
+}
+
+export async function stopLibraryWatcher(ctx: ScannerE2EContext, libraryId: number): Promise<void> {
+  const watcher = ctx.app.get(FileWatcherService);
+  await watcher.stopWatcher(libraryId);
+}
+
+export async function waitForScanCompletion(db: Db, jobId: number, timeoutMs = 30_000, pollMs = 100): Promise<typeof scanJobs.$inferSelect> {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    const [job] = await db.select().from(scanJobs).where(eq(scanJobs.id, jobId)).limit(1);
+    if (!job) throw new Error(`Scan job ${jobId} not found`);
+
+    if (job.status === 'completed') return job;
+    if (job.status === 'failed') {
+      throw new Error(`Scan job ${jobId} failed: ${job.errorMessage ?? 'Unknown error'}`);
+    }
+
+    await sleep(pollMs);
+  }
+
+  throw new Error(`Timed out waiting for scan job ${jobId} to complete`);
+}
+
+export interface LibraryBookState {
+  folderPath: string;
+  status: string;
+  primaryPath: string | null;
+  filePaths: string[];
+}
+
+export async function loadLibraryBookState(db: Db, libraryId: number): Promise<LibraryBookState[]> {
+  const bookRows = await db
+    .select({
+      id: books.id,
+      folderPath: books.folderPath,
+      status: books.status,
+      primaryFileId: books.primaryFileId,
+    })
+    .from(books)
+    .where(eq(books.libraryId, libraryId));
+
+  const states: LibraryBookState[] = [];
+
+  for (const row of bookRows) {
+    const fileRows = await db.select({ absolutePath: bookFiles.absolutePath }).from(bookFiles).where(eq(bookFiles.bookId, row.id));
+
+    let primaryPath: string | null = null;
+    if (row.primaryFileId !== null) {
+      const [primary] = await db.select({ absolutePath: bookFiles.absolutePath }).from(bookFiles).where(eq(bookFiles.id, row.primaryFileId)).limit(1);
+      primaryPath = primary?.absolutePath ?? null;
+    }
+
+    states.push({
+      folderPath: row.folderPath,
+      status: row.status,
+      primaryPath,
+      filePaths: fileRows.map((fileRow) => fileRow.absolutePath).sort(),
+    });
+  }
+
+  return states.sort((a, b) => a.folderPath.localeCompare(b.folderPath));
+}
+
+export async function waitForCondition(check: () => Promise<void>, timeoutMs = 20_000, pollMs = 200): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastError: unknown = null;
+
+  while (Date.now() < deadline) {
+    try {
+      await check();
+      return;
+    } catch (err) {
+      lastError = err;
+      await sleep(pollMs);
+    }
+  }
+
+  throw new Error(`Timed out waiting for condition: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
diff --git a/server/test/scanner-file-ops.e2e-spec.ts b/server/test/scanner-file-ops.e2e-spec.ts
new file mode 100644
index 000000000..0453a162e
--- /dev/null
+++ b/server/test/scanner-file-ops.e2e-spec.ts
@@ -0,0 +1,1633 @@
+vi.mock('../src/modules/scanner/lib/stability', () => ({
+  waitForStability: vi.fn().mockResolvedValue(undefined),
+}));
+
+import { randomUUID } from 'crypto';
+import { mkdir, realpath, rename, rm, stat, writeFile } from 'fs/promises';
+import { dirname, join, relative } from 'path';
+
+import { and, count, eq, isNull, like, sql } from 'drizzle-orm';
+
+import * as schema from '../src/db/schema';
+import type { FixtureEntry } from './e2e/scanner-fixture-builder';
+import { createFixtureTree, file } from './e2e/scanner-fixture-builder';
+import {
+  closeScannerE2EContext,
+  createScannerE2EContext,
+  loadLibraryBookState,
+  seedLibrary,
+  startLibraryWatcher,
+  stopLibraryWatcher,
+  triggerAndWaitForLibraryScan,
+  waitForCondition,
+  type LibraryBookState,
+  type ScannerE2EContext,
+} from './e2e/scanner-harness';
+
+type OrganizationMode = 'book_per_file' | 'book_per_folder';
+type TriggerMode = 'manual' | 'watcher';
+type ScenarioStatus = 'passed' | 'failed' | 'skipped';
+type LibraryKey = 'a' | 'b';
+type BookStatus = 'present' | 'missing';
+
+interface LibrarySetup {
+  key: LibraryKey;
+  rootDir: string;
+  mode: OrganizationMode;
+}
+
+type FileOperation =
+  | { type: 'deleteFile'; path: string }
+  | { type: 'deleteDir'; path: string }
+  | { type: 'move'; from: string; to: string }
+  | { type: 'writeFile'; path: string; content?: string }
+  | { type: 'sleep'; ms: number };
+
+interface LibraryExpectation {
+  statusByFolder: Record<string, BookStatus>;
+  absentFolders?: string[];
+  fileOwners?: Record<string, string>;
+  absentFilePaths?: string[];
+  presentCount?: number;
+  missingCount?: number;
+}
+
+interface StructuralScenario {
+  id: string;
+  trigger: TriggerMode;
+  libraries: LibrarySetup[];
+  entries: FixtureEntry[];
+  operations: FileOperation[];
+  expected: Partial<Record<LibraryKey, LibraryExpectation>>;
+  requiresCaseRename?: boolean;
+}
+
+interface ScenarioRunResult {
+  id: string;
+  trigger: TriggerMode;
+  status: ScenarioStatus;
+  durationMs: number;
+  error?: string;
+}
+
+interface SeededLibrary {
+  key: LibraryKey;
+  rootPath: string;
+  libraryId: number;
+}
+
+interface IntegritySnapshot {
+  orphanBookMetadata: number;
+  orphanBookFiles: number;
+  orphanBookAuthors: number;
+  orphanBookGenres: number;
+  orphanBookTags: number;
+  orphanBookNarrators: number;
+  orphanCollectionBooks: number;
+  orphanUserBookStatus: number;
+  orphanReadingProgress: number;
+  orphanReadingSessions: number;
+  orphanAudiobookProgressBook: number;
+  orphanAudiobookProgressFile: number;
+  orphanBookmarks: number;
+  orphanAnnotations: number;
+  orphanReaderPreferences: number;
+  booksWithoutMetadata: number;
+  invalidPrimaryFileRef: number;
+  duplicatePresentFilePathPerLibrary: number;
+}
+
+interface StatefulSnapshot {
+  metadataTitle: string | null;
+  metadataPublisher: string | null;
+  bookAuthors: number;
+  bookGenres: number;
+  bookTags: number;
+  bookNarrators: number;
+  collectionBooks: number;
+  userBookStatus: number;
+  readingProgress: number;
+  readingSessions: number;
+  audiobookProgress: number;
+  bookmarks: number;
+  annotations: number;
+  readerPreferences: number;
+}
+
+const SCENARIO_TIMEOUT_MS = 120_000;
+
+const structuralScenarios: StructuralScenario[] = [
+  {
+    id: 'manual-delete-primary-file-marks-missing',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [{ type: 'deleteFile', path: 'lib-a/Book/book.epub' }],
+    expected: { a: { statusByFolder: { Book: 'missing' }, presentCount: 0, missingCount: 1 } },
+  },
+  {
+    id: 'manual-delete-folder-marks-only-removed-book-missing',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Shelf/BookOne/one.epub'), file('lib-a/Shelf/BookTwo/two.epub')],
+    operations: [{ type: 'deleteDir', path: 'lib-a/Shelf/BookOne' }],
+    expected: {
+      a: {
+        statusByFolder: {
+          'Shelf/BookOne': 'missing',
+          'Shelf/BookTwo': 'present',
+        },
+        presentCount: 1,
+        missingCount: 1,
+      },
+    },
+  },
+  {
+    id: 'manual-rename-file-in-place',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Book/book.epub', to: 'lib-a/Book/book-renamed.epub' }],
+    expected: {
+      a: {
+        statusByFolder: { Book: 'present' },
+        fileOwners: { 'Book/book-renamed.epub': 'Book' },
+        absentFilePaths: ['Book/book.epub'],
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'manual-rename-folder',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Old/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Old', to: 'lib-a/New' }],
+    expected: {
+      a: {
+        statusByFolder: { Old: 'missing', New: 'present' },
+        fileOwners: { 'New/book.epub': 'New' },
+        presentCount: 1,
+        missingCount: 1,
+      },
+    },
+  },
+  {
+    id: 'manual-move-root-file-into-subfolder',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/book.epub', to: 'lib-a/Shelf/book.epub' }],
+    expected: {
+      a: {
+        statusByFolder: { 'book.epub': 'missing', Shelf: 'present' },
+        fileOwners: { 'Shelf/book.epub': 'Shelf' },
+        presentCount: 1,
+        missingCount: 1,
+      },
+    },
+  },
+  {
+    id: 'manual-move-subfolder-file-to-root',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Shelf/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Shelf/book.epub', to: 'lib-a/book.epub' }],
+    expected: {
+      a: {
+        statusByFolder: { Shelf: 'missing', 'book.epub': 'present' },
+        fileOwners: { 'book.epub': 'book.epub' },
+        presentCount: 1,
+        missingCount: 1,
+      },
+    },
+  },
+  {
+    id: 'manual-cross-library-file-move',
+    trigger: 'manual',
+    libraries: [
+      { key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' },
+      { key: 'b', rootDir: 'lib-b', mode: 'book_per_folder' },
+    ],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Book/book.epub', to: 'lib-b/Inbox/book.epub' }],
+    expected: {
+      a: { statusByFolder: {}, absentFolders: ['Book'], presentCount: 0, missingCount: 0 },
+      b: {
+        statusByFolder: { Inbox: 'present' },
+        fileOwners: { 'Inbox/book.epub': 'Inbox' },
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'manual-cross-library-folder-move',
+    trigger: 'manual',
+    libraries: [
+      { key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' },
+      { key: 'b', rootDir: 'lib-b', mode: 'book_per_folder' },
+    ],
+    entries: [file('lib-a/Series/Book/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Series/Book', to: 'lib-b/Incoming/Book' }],
+    expected: {
+      a: { statusByFolder: {}, absentFolders: ['Series/Book'], presentCount: 0, missingCount: 0 },
+      b: {
+        statusByFolder: { 'Incoming/Book': 'present' },
+        fileOwners: { 'Incoming/Book/book.epub': 'Incoming/Book' },
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'manual-multi-step-churn',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/A/One/one.epub'), file('lib-a/A/Two/two.epub')],
+    operations: [
+      { type: 'move', from: 'lib-a/A/One/one.epub', to: 'lib-a/A/One/one-renamed.epub' },
+      { type: 'move', from: 'lib-a/A/Two', to: 'lib-a/B/Two' },
+      { type: 'deleteFile', path: 'lib-a/A/One/one-renamed.epub' },
+      { type: 'writeFile', path: 'lib-a/C/three.epub' },
+    ],
+    expected: {
+      a: {
+        statusByFolder: {
+          'A/One': 'missing',
+          'A/Two': 'missing',
+          'B/Two': 'present',
+          C: 'present',
+        },
+        fileOwners: {
+          'B/Two/two.epub': 'B/Two',
+          'C/three.epub': 'C',
+        },
+        presentCount: 2,
+        missingCount: 2,
+      },
+    },
+  },
+  {
+    id: 'manual-book-per-file-delete-and-move',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_file' }],
+    entries: [file('lib-a/track1.mp3'), file('lib-a/track2.mp3')],
+    operations: [
+      { type: 'move', from: 'lib-a/track1.mp3', to: 'lib-a/Archive/track1.mp3' },
+      { type: 'deleteFile', path: 'lib-a/track2.mp3' },
+    ],
+    expected: {
+      a: {
+        statusByFolder: {
+          'track1.mp3': 'missing',
+          'track2.mp3': 'missing',
+          'Archive/track1.mp3': 'present',
+        },
+        fileOwners: { 'Archive/track1.mp3': 'Archive/track1.mp3' },
+        presentCount: 1,
+        missingCount: 2,
+      },
+    },
+  },
+  {
+    id: 'manual-move-into-existing-folder-merges',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Source/source.epub'), file('lib-a/Destination/dest.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Source/source.epub', to: 'lib-a/Destination/source.epub' }],
+    expected: {
+      a: {
+        statusByFolder: {
+          Source: 'missing',
+          Destination: 'present',
+        },
+        fileOwners: {
+          'Destination/dest.epub': 'Destination',
+          'Destination/source.epub': 'Destination',
+        },
+        absentFilePaths: ['Source/source.epub'],
+        presentCount: 1,
+        missingCount: 1,
+      },
+    },
+  },
+  {
+    id: 'manual-cross-library-move-into-existing-folder-merges',
+    trigger: 'manual',
+    libraries: [
+      { key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' },
+      { key: 'b', rootDir: 'lib-b', mode: 'book_per_folder' },
+    ],
+    entries: [file('lib-a/Source/book.epub'), file('lib-b/Inbox/existing.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Source/book.epub', to: 'lib-b/Inbox/book.epub' }],
+    expected: {
+      a: {
+        statusByFolder: { Source: 'missing' },
+        presentCount: 0,
+        missingCount: 1,
+      },
+      b: {
+        statusByFolder: { Inbox: 'present' },
+        fileOwners: {
+          'Inbox/existing.epub': 'Inbox',
+          'Inbox/book.epub': 'Inbox',
+        },
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'manual-delete-and-recreate-same-path',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [
+      { type: 'deleteFile', path: 'lib-a/Book/book.epub' },
+      { type: 'writeFile', path: 'lib-a/Book/book.epub' },
+    ],
+    expected: { a: { statusByFolder: { Book: 'present' }, presentCount: 1, missingCount: 0 } },
+  },
+  {
+    id: 'manual-delete-and-recreate-folder-with-new-file',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Swap/old.epub')],
+    operations: [
+      { type: 'deleteDir', path: 'lib-a/Swap' },
+      { type: 'writeFile', path: 'lib-a/Swap/new.epub' },
+    ],
+    expected: {
+      a: {
+        statusByFolder: { Swap: 'present' },
+        fileOwners: { 'Swap/new.epub': 'Swap' },
+        absentFilePaths: ['Swap/old.epub'],
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'manual-book-per-file-folder-move-multi-file',
+    trigger: 'manual',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_file' }],
+    entries: [file('lib-a/Batch/one.mp3'), file('lib-a/Batch/two.mp3')],
+    operations: [{ type: 'move', from: 'lib-a/Batch', to: 'lib-a/Archive/Batch' }],
+    expected: {
+      a: {
+        statusByFolder: {
+          'Batch/one.mp3': 'missing',
+          'Batch/two.mp3': 'missing',
+          'Archive/Batch/one.mp3': 'present',
+          'Archive/Batch/two.mp3': 'present',
+        },
+        fileOwners: {
+          'Archive/Batch/one.mp3': 'Archive/Batch/one.mp3',
+          'Archive/Batch/two.mp3': 'Archive/Batch/two.mp3',
+        },
+        presentCount: 2,
+        missingCount: 2,
+      },
+    },
+  },
+  {
+    id: 'manual-cross-library-move-then-reseed-source',
+    trigger: 'manual',
+    libraries: [
+      { key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' },
+      { key: 'b', rootDir: 'lib-b', mode: 'book_per_folder' },
+    ],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [
+      { type: 'move', from: 'lib-a/Book/book.epub', to: 'lib-b/Inbox/book.epub' },
+      { type: 'writeFile', path: 'lib-a/Book/book.epub' },
+    ],
+    expected: {
+      a: {
+        statusByFolder: { Book: 'present' },
+        fileOwners: { 'Book/book.epub': 'Book' },
+        presentCount: 1,
+        missingCount: 0,
+      },
+      b: {
+        statusByFolder: { Inbox: 'present' },
+        fileOwners: { 'Inbox/book.epub': 'Inbox' },
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'watcher-delete-primary-file-marks-missing',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [{ type: 'deleteFile', path: 'lib-a/Book/book.epub' }],
+    expected: { a: { statusByFolder: { Book: 'missing' }, presentCount: 0, missingCount: 1 } },
+  },
+  {
+    id: 'watcher-delete-folder',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Shelf/One/one.epub'), file('lib-a/Shelf/Two/two.epub')],
+    operations: [{ type: 'deleteDir', path: 'lib-a/Shelf/One' }],
+    expected: {
+      a: {
+        statusByFolder: {
+          'Shelf/One': 'missing',
+          'Shelf/Two': 'present',
+        },
+        presentCount: 1,
+        missingCount: 1,
+      },
+    },
+  },
+  {
+    id: 'watcher-rename-file-in-place',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Book/book.epub', to: 'lib-a/Book/book-renamed.epub' }],
+    expected: {
+      a: {
+        statusByFolder: { Book: 'present' },
+        fileOwners: { 'Book/book-renamed.epub': 'Book' },
+        absentFilePaths: ['Book/book.epub'],
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'watcher-rename-folder',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Old/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Old', to: 'lib-a/New' }],
+    expected: {
+      a: {
+        statusByFolder: { New: 'present' },
+        absentFolders: ['Old'],
+        fileOwners: { 'New/book.epub': 'New' },
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'watcher-move-root-file-into-subfolder',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/book.epub', to: 'lib-a/Shelf/book.epub' }],
+    expected: {
+      a: {
+        statusByFolder: { Shelf: 'present' },
+        fileOwners: { 'Shelf/book.epub': 'Shelf' },
+      },
+    },
+  },
+  {
+    id: 'watcher-move-subfolder-file-to-root',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Shelf/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Shelf/book.epub', to: 'lib-a/book.epub' }],
+    expected: {
+      a: {
+        statusByFolder: { 'book.epub': 'present' },
+        fileOwners: { 'book.epub': 'book.epub' },
+      },
+    },
+  },
+  {
+    id: 'watcher-cross-library-file-move',
+    trigger: 'watcher',
+    libraries: [
+      { key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' },
+      { key: 'b', rootDir: 'lib-b', mode: 'book_per_folder' },
+    ],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Book/book.epub', to: 'lib-b/Inbox/book.epub' }],
+    expected: {
+      a: { statusByFolder: {}, absentFolders: ['Book'], presentCount: 0, missingCount: 0 },
+      b: {
+        statusByFolder: { Inbox: 'present' },
+        fileOwners: { 'Inbox/book.epub': 'Inbox' },
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'watcher-cross-library-folder-move',
+    trigger: 'watcher',
+    libraries: [
+      { key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' },
+      { key: 'b', rootDir: 'lib-b', mode: 'book_per_folder' },
+    ],
+    entries: [file('lib-a/Series/Book/book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Series/Book', to: 'lib-b/Incoming/Book' }],
+    expected: {
+      a: { statusByFolder: {}, absentFolders: ['Series/Book'], presentCount: 0, missingCount: 0 },
+      b: {
+        statusByFolder: { 'Incoming/Book': 'present' },
+        fileOwners: { 'Incoming/Book/book.epub': 'Incoming/Book' },
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'watcher-case-only-file-rename',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Book/Book.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Book/Book.epub', to: 'lib-a/Book/book.epub' }],
+    expected: {
+      a: {
+        statusByFolder: { Book: 'present' },
+        fileOwners: { 'Book/book.epub': 'Book' },
+        absentFilePaths: ['Book/Book.epub'],
+        presentCount: 1,
+      },
+    },
+    requiresCaseRename: true,
+  },
+  {
+    id: 'watcher-non-content-file-creates-ignored',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [
+      { type: 'writeFile', path: 'lib-a/Book/cover.jpg' },
+      { type: 'writeFile', path: 'lib-a/Book/metadata.opf' },
+    ],
+    expected: { a: { statusByFolder: { Book: 'present' }, presentCount: 1, missingCount: 0 } },
+  },
+  {
+    id: 'watcher-non-content-file-delete-ignored',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Book/book.epub'), file('lib-a/Book/cover.jpg')],
+    operations: [{ type: 'deleteFile', path: 'lib-a/Book/cover.jpg' }],
+    expected: { a: { statusByFolder: { Book: 'present' }, presentCount: 1, missingCount: 0 } },
+  },
+  {
+    id: 'watcher-book-per-file-delete-then-restore',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_file' }],
+    entries: [file('lib-a/Track.mp3')],
+    operations: [
+      { type: 'deleteFile', path: 'lib-a/Track.mp3' },
+      { type: 'sleep', ms: 900 },
+      { type: 'writeFile', path: 'lib-a/Track.mp3' },
+    ],
+    expected: { a: { statusByFolder: { 'Track.mp3': 'present' }, presentCount: 1, missingCount: 0 } },
+  },
+  {
+    id: 'watcher-move-into-existing-folder-merges',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Source/source.epub'), file('lib-a/Destination/dest.epub')],
+    operations: [{ type: 'move', from: 'lib-a/Source/source.epub', to: 'lib-a/Destination/source.epub' }],
+    expected: {
+      a: {
+        statusByFolder: {
+          Source: 'missing',
+          Destination: 'present',
+        },
+        fileOwners: {
+          'Destination/dest.epub': 'Destination',
+          'Destination/source.epub': 'Destination',
+        },
+        absentFilePaths: ['Source/source.epub'],
+        presentCount: 1,
+        missingCount: 1,
+      },
+    },
+  },
+  {
+    id: 'watcher-delete-and-recreate-same-path-within-debounce',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [
+      { type: 'deleteFile', path: 'lib-a/Book/book.epub' },
+      { type: 'writeFile', path: 'lib-a/Book/book.epub' },
+    ],
+    expected: { a: { statusByFolder: { Book: 'present' }, presentCount: 1, missingCount: 0 } },
+  },
+  {
+    id: 'watcher-delete-and-recreate-folder-with-new-file',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [file('lib-a/Swap/old.epub')],
+    operations: [
+      { type: 'deleteDir', path: 'lib-a/Swap' },
+      { type: 'sleep', ms: 900 },
+      { type: 'writeFile', path: 'lib-a/Swap/new.epub' },
+    ],
+    expected: {
+      a: {
+        statusByFolder: { Swap: 'present' },
+        fileOwners: { 'Swap/new.epub': 'Swap' },
+        absentFilePaths: ['Swap/old.epub'],
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'watcher-cross-library-move-then-reseed-source',
+    trigger: 'watcher',
+    libraries: [
+      { key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' },
+      { key: 'b', rootDir: 'lib-b', mode: 'book_per_folder' },
+    ],
+    entries: [file('lib-a/Book/book.epub')],
+    operations: [
+      { type: 'move', from: 'lib-a/Book/book.epub', to: 'lib-b/Inbox/book.epub' },
+      { type: 'sleep', ms: 900 },
+      { type: 'writeFile', path: 'lib-a/Book/book.epub' },
+    ],
+    expected: {
+      a: {
+        statusByFolder: { Book: 'present' },
+        fileOwners: { 'Book/book.epub': 'Book' },
+        presentCount: 1,
+        missingCount: 0,
+      },
+      b: {
+        statusByFolder: { Inbox: 'present' },
+        fileOwners: { 'Inbox/book.epub': 'Inbox' },
+        presentCount: 1,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'watcher-create-then-delete-new-path-within-debounce',
+    trigger: 'watcher',
+    libraries: [{ key: 'a', rootDir: 'lib-a', mode: 'book_per_folder' }],
+    entries: [],
+    operations: [
+      { type: 'writeFile', path: 'lib-a/Temp/new.epub' },
+      { type: 'deleteFile', path: 'lib-a/Temp/new.epub' },
+    ],
+    expected: {
+      a: {
+        statusByFolder: {},
+        presentCount: 0,
+        missingCount: 0,
+      },
+    },
+  },
+  {
+    id: 'watcher-book-per-file-cross-library-folder-move-multi-file',
+    trigger: 'watcher',
+    libraries: [
+      { key: 'a', rootDir: 'lib-a', mode: 'book_per_file' },
+      { key: 'b', rootDir: 'lib-b', mode: 'book_per_file' },
+    ],
+    entries: [file('lib-a/Batch/one.mp3'), file('lib-a/Batch/two.mp3')],
+    operations: [{ type: 'move', from: 'lib-a/Batch', to: 'lib-b/Import/Batch' }],
+    expected: {
+      a: {
+        statusByFolder: {},
+        absentFolders: ['Batch/one.mp3', 'Batch/two.mp3'],
+        presentCount: 0,
+        missingCount: 0,
+      },
+      b: {
+        statusByFolder: {
+          'Import/Batch/one.mp3': 'present',
+          'Import/Batch/two.mp3': 'present',
+        },
+        fileOwners: {
+          'Import/Batch/one.mp3': 'Import/Batch/one.mp3',
+          'Import/Batch/two.mp3': 'Import/Batch/two.mp3',
+        },
+        presentCount: 2,
+        missingCount: 0,
+      },
+    },
+  },
+];
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function applyOperation(rootPath: string, operation: FileOperation): Promise<void> {
+  switch (operation.type) {
+    case 'deleteFile':
+      await rm(join(rootPath, operation.path), { force: true });
+      break;
+    case 'deleteDir':
+      await rm(join(rootPath, operation.path), { recursive: true, force: true });
+      break;
+    case 'move': {
+      const from = join(rootPath, operation.from);
+      const to = join(rootPath, operation.to);
+      await mkdir(dirname(to), { recursive: true });
+      await rename(from, to);
+      break;
+    }
+    case 'writeFile': {
+      const outputPath = join(rootPath, operation.path);
+      await mkdir(dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, operation.content ?? `${operation.path}\n`.repeat(600));
+      break;
+    }
+    case 'sleep':
+      await sleep(operation.ms);
+      break;
+  }
+}
+
+function assertLibraryExpectation(rootPath: string, actual: LibraryBookState[], expectation: LibraryExpectation): void {
+  const byFolder = new Map(actual.map((book) => [relative(rootPath, book.folderPath), book]));
+
+  for (const [folderPath, status] of Object.entries(expectation.statusByFolder)) {
+    const book = byFolder.get(folderPath);
+    expect(book, `expected book for folder "${folderPath}"`).toBeDefined();
+    expect(book!.status).toBe(status);
+  }
+
+  for (const folderPath of expectation.absentFolders ?? []) {
+    expect(byFolder.has(folderPath), `folder "${folderPath}" should be absent`).toBe(false);
+  }
+
+  if (expectation.presentCount !== undefined) {
+    expect(actual.filter((book) => book.status === 'present')).toHaveLength(expectation.presentCount);
+  }
+
+  if (expectation.missingCount !== undefined) {
+    expect(actual.filter((book) => book.status === 'missing')).toHaveLength(expectation.missingCount);
+  }
+
+  for (const [filePath, expectedOwnerFolder] of Object.entries(expectation.fileOwners ?? {})) {
+    const absoluteFilePath = join(rootPath, filePath);
+    const owners = actual
+      .filter((book) => book.filePaths.includes(absoluteFilePath))
+      .map((book) => relative(rootPath, book.folderPath))
+      .sort();
+    expect(owners).toEqual([expectedOwnerFolder]);
+  }
+
+  for (const filePath of expectation.absentFilePaths ?? []) {
+    const absoluteFilePath = join(rootPath, filePath);
+    const owners = actual.filter((book) => book.filePaths.includes(absoluteFilePath));
+    expect(owners, `file "${filePath}" should not be owned by any book`).toHaveLength(0);
+  }
+}
+
+async function loadIntegritySnapshot(db: ScannerE2EContext['db']): Promise<IntegritySnapshot> {
+  const [orphanBookMetadata] = await db
+    .select({ value: count() })
+    .from(schema.bookMetadata)
+    .leftJoin(schema.books, eq(schema.bookMetadata.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanBookFiles] = await db
+    .select({ value: count() })
+    .from(schema.bookFiles)
+    .leftJoin(schema.books, eq(schema.bookFiles.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanBookAuthors] = await db
+    .select({ value: count() })
+    .from(schema.bookAuthors)
+    .leftJoin(schema.books, eq(schema.bookAuthors.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanBookGenres] = await db
+    .select({ value: count() })
+    .from(schema.bookGenres)
+    .leftJoin(schema.books, eq(schema.bookGenres.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanBookTags] = await db
+    .select({ value: count() })
+    .from(schema.bookTags)
+    .leftJoin(schema.books, eq(schema.bookTags.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanBookNarrators] = await db
+    .select({ value: count() })
+    .from(schema.bookNarrators)
+    .leftJoin(schema.books, eq(schema.bookNarrators.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanCollectionBooks] = await db
+    .select({ value: count() })
+    .from(schema.collectionBooks)
+    .leftJoin(schema.books, eq(schema.collectionBooks.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanUserBookStatus] = await db
+    .select({ value: count() })
+    .from(schema.userBookStatus)
+    .leftJoin(schema.books, eq(schema.userBookStatus.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanReadingProgress] = await db
+    .select({ value: count() })
+    .from(schema.readingProgress)
+    .leftJoin(schema.bookFiles, eq(schema.readingProgress.bookFileId, schema.bookFiles.id))
+    .where(isNull(schema.bookFiles.id));
+
+  const [orphanReadingSessions] = await db
+    .select({ value: count() })
+    .from(schema.readingSessions)
+    .leftJoin(schema.bookFiles, eq(schema.readingSessions.bookFileId, schema.bookFiles.id))
+    .where(isNull(schema.bookFiles.id));
+
+  const [orphanAudiobookProgressBook] = await db
+    .select({ value: count() })
+    .from(schema.audiobookProgress)
+    .leftJoin(schema.books, eq(schema.audiobookProgress.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanAudiobookProgressFile] = await db
+    .select({ value: count() })
+    .from(schema.audiobookProgress)
+    .leftJoin(schema.bookFiles, eq(schema.audiobookProgress.currentFileId, schema.bookFiles.id))
+    .where(isNull(schema.bookFiles.id));
+
+  const [orphanBookmarks] = await db
+    .select({ value: count() })
+    .from(schema.bookmarks)
+    .leftJoin(schema.books, eq(schema.bookmarks.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanAnnotations] = await db
+    .select({ value: count() })
+    .from(schema.annotations)
+    .leftJoin(schema.books, eq(schema.annotations.bookId, schema.books.id))
+    .where(isNull(schema.books.id));
+
+  const [orphanReaderPreferences] = await db
+    .select({ value: count() })
+    .from(schema.readerPreferences)
+    .leftJoin(schema.bookFiles, eq(schema.readerPreferences.bookFileId, schema.bookFiles.id))
+    .where(isNull(schema.bookFiles.id));
+
+  const [booksWithoutMetadata] = await db
+    .select({ value: count() })
+    .from(schema.books)
+    .leftJoin(schema.bookMetadata, eq(schema.bookMetadata.bookId, schema.books.id))
+    .where(isNull(schema.bookMetadata.bookId));
+
+  const invalidPrimaryRows = await db
+    .select({ bookId: schema.books.id })
+    .from(schema.books)
+    .leftJoin(schema.bookFiles, eq(schema.bookFiles.id, schema.books.primaryFileId))
+    .where(
+      sql`${schema.books.status} = 'present' AND ${schema.books.primaryFileId} IS NOT NULL AND (${schema.bookFiles.id} IS NULL OR ${schema.bookFiles.bookId} <> ${schema.books.id})`,
+    );
+
+  const duplicatePresentRows = await db
+    .select({
+      libraryId: schema.books.libraryId,
+      absolutePath: schema.bookFiles.absolutePath,
+      fileCount: sql<number>`count(*)`,
+    })
+    .from(schema.bookFiles)
+    .innerJoin(schema.books, eq(schema.books.id, schema.bookFiles.bookId))
+    .where(eq(schema.books.status, 'present'))
+    .groupBy(schema.books.libraryId, schema.bookFiles.absolutePath)
+    .having(sql`count(*) > 1`);
+
+  return {
+    orphanBookMetadata: Number(orphanBookMetadata.value),
+    orphanBookFiles: Number(orphanBookFiles.value),
+    orphanBookAuthors: Number(orphanBookAuthors.value),
+    orphanBookGenres: Number(orphanBookGenres.value),
+    orphanBookTags: Number(orphanBookTags.value),
+    orphanBookNarrators: Number(orphanBookNarrators.value),
+    orphanCollectionBooks: Number(orphanCollectionBooks.value),
+    orphanUserBookStatus: Number(orphanUserBookStatus.value),
+    orphanReadingProgress: Number(orphanReadingProgress.value),
+    orphanReadingSessions: Number(orphanReadingSessions.value),
+    orphanAudiobookProgressBook: Number(orphanAudiobookProgressBook.value),
+    orphanAudiobookProgressFile: Number(orphanAudiobookProgressFile.value),
+    orphanBookmarks: Number(orphanBookmarks.value),
+    orphanAnnotations: Number(orphanAnnotations.value),
+    orphanReaderPreferences: Number(orphanReaderPreferences.value),
+    booksWithoutMetadata: Number(booksWithoutMetadata.value),
+    invalidPrimaryFileRef: invalidPrimaryRows.length,
+    duplicatePresentFilePathPerLibrary: duplicatePresentRows.length,
+  };
+}
+
+async function assertNoIntegrityViolations(db: ScannerE2EContext['db']): Promise<void> {
+  const snapshot = await loadIntegritySnapshot(db);
+  for (const [key, value] of Object.entries(snapshot)) {
+    expect(value, `integrity violation ${key}`).toBe(0);
+  }
+}
+
+async function resetScannerFileOpsState(db: ScannerE2EContext['db']): Promise<void> {
+  await db.delete(schema.libraries).where(like(schema.libraries.name, 'scanner-file-ops-%'));
+  await db.delete(schema.users).where(like(schema.users.username, 'state-user-%'));
+}
+
+async function supportsCaseOnlyRename(rootPath: string): Promise<boolean> {
+  const probeDir = join(rootPath, 'case-probe');
+  const upperPath = join(probeDir, 'CaseProbe.epub');
+  const lowerPath = join(probeDir, 'caseprobe.epub');
+  await mkdir(probeDir, { recursive: true });
+  await writeFile(upperPath, 'probe');
+  try {
+    await rename(upperPath, lowerPath);
+    const renamed = await stat(lowerPath).catch(() => null);
+    return renamed?.isFile() ?? false;
+  } catch {
+    return false;
+  } finally {
+    await rm(probeDir, { recursive: true, force: true });
+  }
+}
+
+function seededLibraryByKey(seeded: SeededLibrary[], key: LibraryKey): SeededLibrary {
+  const lib = seeded.find((entry) => entry.key === key);
+  if (!lib) throw new Error(`Missing seeded library for key "${key}"`);
+  return lib;
+}
+
+async function assertScenarioExpectations(
+  context: ScannerE2EContext,
+  seeded: SeededLibrary[],
+  expected: Partial<Record<LibraryKey, LibraryExpectation>>,
+): Promise<void> {
+  for (const key of Object.keys(expected) as LibraryKey[]) {
+    const expectation = expected[key];
+    if (!expectation) continue;
+    const lib = seededLibraryByKey(seeded, key);
+    const actual = await loadLibraryBookState(context.db, lib.libraryId);
+    assertLibraryExpectation(lib.rootPath, actual, expectation);
+  }
+}
+
+async function runStructuralScenario(context: ScannerE2EContext, scenario: StructuralScenario, results: ScenarioRunResult[]): Promise<void> {
+  const fixture = await createFixtureTree(scenario.entries, `scanner-file-ops-${scenario.id}-`);
+  const startedAt = Date.now();
+  const seeded: SeededLibrary[] = [];
+  const startedWatchers: number[] = [];
+
+  try {
+    await resetScannerFileOpsState(context.db);
+
+    if (scenario.requiresCaseRename && !(await supportsCaseOnlyRename(fixture.rootPath))) {
+      results.push({
+        id: scenario.id,
+        trigger: scenario.trigger,
+        status: 'skipped',
+        durationMs: Date.now() - startedAt,
+      });
+      return;
+    }
+
+    for (const library of scenario.libraries) {
+      const requestedRootPath = join(fixture.rootPath, library.rootDir);
+      await mkdir(requestedRootPath, { recursive: true });
+      const rootPath = await realpath(requestedRootPath);
+      const seededLibrary = await seedLibrary(context.db, {
+        rootPath,
+        mode: library.mode,
+        watch: false,
+        name: `scanner-file-ops-${scenario.id}-${library.key}-${randomUUID()}`,
+      });
+      seeded.push({
+        key: library.key,
+        rootPath,
+        libraryId: seededLibrary.libraryId,
+      });
+    }
+
+    for (const library of seeded) {
+      await triggerAndWaitForLibraryScan(context, library.libraryId);
+    }
+
+    if (scenario.trigger === 'watcher') {
+      for (const library of seeded) {
+        await startLibraryWatcher(context, library.libraryId, [library.rootPath]);
+        startedWatchers.push(library.libraryId);
+      }
+    }
+
+    for (const operation of scenario.operations) {
+      await applyOperation(fixture.rootPath, operation);
+    }
+
+    if (scenario.trigger === 'manual') {
+      for (const library of seeded) {
+        await triggerAndWaitForLibraryScan(context, library.libraryId);
+      }
+      await assertScenarioExpectations(context, seeded, scenario.expected);
+      await assertNoIntegrityViolations(context.db);
+    } else {
+      await waitForCondition(async () => {
+        await assertScenarioExpectations(context, seeded, scenario.expected);
+        await assertNoIntegrityViolations(context.db);
+      }, 40_000);
+    }
+
+    results.push({
+      id: scenario.id,
+      trigger: scenario.trigger,
+      status: 'passed',
+      durationMs: Date.now() - startedAt,
+    });
+  } catch (err) {
+    results.push({
+      id: scenario.id,
+      trigger: scenario.trigger,
+      status: 'failed',
+      durationMs: Date.now() - startedAt,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    throw err;
+  } finally {
+    for (const libraryId of startedWatchers) {
+      await stopLibraryWatcher(context, libraryId);
+    }
+    await fixture.cleanup();
+  }
+}
+
+async function getBookByFolderPath(db: ScannerE2EContext['db'], libraryId: number, folderPath: string): Promise<typeof schema.books.$inferSelect> {
+  const [book] = await db
+    .select()
+    .from(schema.books)
+    .where(and(eq(schema.books.libraryId, libraryId), eq(schema.books.folderPath, folderPath)))
+    .limit(1);
+  if (!book) {
+    throw new Error(`Book not found for library=${libraryId} folderPath="${folderPath}"`);
+  }
+  return book;
+}
+
+async function getBookById(db: ScannerE2EContext['db'], bookId: number): Promise<typeof schema.books.$inferSelect> {
+  const [book] = await db.select().from(schema.books).where(eq(schema.books.id, bookId)).limit(1);
+  if (!book) {
+    throw new Error(`Book id=${bookId} not found`);
+  }
+  return book;
+}
+
+async function createRegularUsers(db: ScannerE2EContext['db']): Promise<[number, number]> {
+  const suffix = randomUUID();
+  const users = await db
+    .insert(schema.users)
+    .values([
+      {
+        username: `state-user-a-${suffix}`,
+        name: 'State User A',
+        email: `state-user-a-${suffix}@example.com`,
+        passwordHash: `hash-${suffix}-a`,
+        isSuperuser: false,
+      },
+      {
+        username: `state-user-b-${suffix}`,
+        name: 'State User B',
+        email: `state-user-b-${suffix}@example.com`,
+        passwordHash: `hash-${suffix}-b`,
+        isSuperuser: false,
+      },
+    ])
+    .returning({ id: schema.users.id });
+  return [users[0]!.id, users[1]!.id];
+}
+
+async function loadStatefulSnapshot(db: ScannerE2EContext['db'], bookId: number, primaryFileId: number): Promise<StatefulSnapshot> {
+  const [metadata] = await db
+    .select({ title: schema.bookMetadata.title, publisher: schema.bookMetadata.publisher })
+    .from(schema.bookMetadata)
+    .where(eq(schema.bookMetadata.bookId, bookId))
+    .limit(1);
+
+  const [bookAuthors] = await db.select({ value: count() }).from(schema.bookAuthors).where(eq(schema.bookAuthors.bookId, bookId));
+  const [bookGenres] = await db.select({ value: count() }).from(schema.bookGenres).where(eq(schema.bookGenres.bookId, bookId));
+  const [bookTags] = await db.select({ value: count() }).from(schema.bookTags).where(eq(schema.bookTags.bookId, bookId));
+  const [bookNarrators] = await db.select({ value: count() }).from(schema.bookNarrators).where(eq(schema.bookNarrators.bookId, bookId));
+  const [collectionBooks] = await db.select({ value: count() }).from(schema.collectionBooks).where(eq(schema.collectionBooks.bookId, bookId));
+  const [userBookStatus] = await db.select({ value: count() }).from(schema.userBookStatus).where(eq(schema.userBookStatus.bookId, bookId));
+  const [readingProgress] = await db
+    .select({ value: count() })
+    .from(schema.readingProgress)
+    .where(eq(schema.readingProgress.bookFileId, primaryFileId));
+  const [readingSessions] = await db
+    .select({ value: count() })
+    .from(schema.readingSessions)
+    .where(eq(schema.readingSessions.bookFileId, primaryFileId));
+  const [audiobookProgress] = await db.select({ value: count() }).from(schema.audiobookProgress).where(eq(schema.audiobookProgress.bookId, bookId));
+  const [bookmarks] = await db.select({ value: count() }).from(schema.bookmarks).where(eq(schema.bookmarks.bookId, bookId));
+  const [annotations] = await db.select({ value: count() }).from(schema.annotations).where(eq(schema.annotations.bookId, bookId));
+  const [readerPreferences] = await db
+    .select({ value: count() })
+    .from(schema.readerPreferences)
+    .where(eq(schema.readerPreferences.bookFileId, primaryFileId));
+
+  return {
+    metadataTitle: metadata?.title ?? null,
+    metadataPublisher: metadata?.publisher ?? null,
+    bookAuthors: Number(bookAuthors.value),
+    bookGenres: Number(bookGenres.value),
+    bookTags: Number(bookTags.value),
+    bookNarrators: Number(bookNarrators.value),
+    collectionBooks: Number(collectionBooks.value),
+    userBookStatus: Number(userBookStatus.value),
+    readingProgress: Number(readingProgress.value),
+    readingSessions: Number(readingSessions.value),
+    audiobookProgress: Number(audiobookProgress.value),
+    bookmarks: Number(bookmarks.value),
+    annotations: Number(annotations.value),
+    readerPreferences: Number(readerPreferences.value),
+  };
+}
+
+async function seedStatefulData(db: ScannerE2EContext['db'], bookId: number, primaryFileId: number): Promise<{ snapshot: StatefulSnapshot }> {
+  const [userA, userB] = await createRegularUsers(db);
+  const suffix = randomUUID();
+  const now = new Date();
+
+  await db
+    .update(schema.bookMetadata)
+    .set({
+      title: 'Stateful Scanner Fixture',
+      publisher: 'Stateful Publishing',
+      seriesName: 'Scanner Stateful Series',
+      seriesIndex: 1,
+    })
+    .where(eq(schema.bookMetadata.bookId, bookId));
+
+  const [author] = await db
+    .insert(schema.authors)
+    .values({ name: `State Author ${suffix}` })
+    .returning({ id: schema.authors.id });
+  await db.insert(schema.bookAuthors).values({ bookId, authorId: author.id, displayOrder: 0 });
+
+  const [genre] = await db
+    .insert(schema.genres)
+    .values({ name: `State Genre ${suffix}` })
+    .returning({ id: schema.genres.id });
+  await db.insert(schema.bookGenres).values({ bookId, genreId: genre.id });
+
+  const [tag] = await db
+    .insert(schema.tags)
+    .values({ name: `State Tag ${suffix}` })
+    .returning({ id: schema.tags.id });
+  await db.insert(schema.bookTags).values({ bookId, tagId: tag.id });
+
+  const [narrator] = await db
+    .insert(schema.narrators)
+    .values({ name: `State Narrator ${suffix}` })
+    .returning({ id: schema.narrators.id });
+  await db.insert(schema.bookNarrators).values({ bookId, narratorId: narrator.id, displayOrder: 0 });
+
+  const [collection] = await db
+    .insert(schema.collections)
+    .values({ userId: userA, name: `State Collection ${suffix}`, description: 'Stateful collection fixture' })
+    .returning({ id: schema.collections.id });
+  await db.insert(schema.collectionBooks).values({ collectionId: collection.id, bookId });
+
+  await db.insert(schema.userBookStatus).values([
+    { userId: userA, bookId, status: 'reading', source: 'manual' },
+    { userId: userB, bookId, status: 'on_hold', source: 'manual' },
+  ]);
+
+  await db.insert(schema.readingProgress).values([
+    { userId: userA, bookFileId: primaryFileId, percentage: 42.5, positionSeconds: 220.5, pageNumber: 12 },
+    { userId: userB, bookFileId: primaryFileId, percentage: 17.25, positionSeconds: 80.25, pageNumber: 4 },
+  ]);
+
+  await db.insert(schema.readingSessions).values([
+    {
+      userId: userA,
+      bookFileId: primaryFileId,
+      sessionId: `session-${suffix}-a`,
+      startedAt: new Date(now.getTime() - 300_000),
+      endedAt: new Date(now.getTime() - 240_000),
+      durationSeconds: 60,
+      progressDelta: 2.5,
+      endProgress: 42.5,
+    },
+    {
+      userId: userB,
+      bookFileId: primaryFileId,
+      sessionId: `session-${suffix}-b`,
+      startedAt: new Date(now.getTime() - 180_000),
+      endedAt: new Date(now.getTime() - 120_000),
+      durationSeconds: 60,
+      progressDelta: 1.5,
+      endProgress: 17.25,
+    },
+  ]);
+
+  await db.insert(schema.audiobookProgress).values({ userId: userA, bookId, currentFileId: primaryFileId, percentage: 42.5, positionSeconds: 220.5 });
+
+  await db.insert(schema.bookmarks).values([
+    { userId: userA, bookId, title: 'State Bookmark A', cfi: 'epubcfi(/6/2[chapter1]!/4/2/14)' },
+    { userId: userB, bookId, title: 'State Bookmark B', cfi: 'epubcfi(/6/4[chapter2]!/4/6/8)' },
+  ]);
+
+  await db.insert(schema.annotations).values([
+    {
+      userId: userA,
+      bookId,
+      cfi: 'epubcfi(/6/2[chapter1]!/4/2/14)',
+      text: 'State annotation A',
+      color: 'yellow',
+      style: 'highlight',
+    },
+    {
+      userId: userB,
+      bookId,
+      cfi: 'epubcfi(/6/4[chapter2]!/4/6/8)',
+      text: 'State annotation B',
+      color: 'green',
+      style: 'underline',
+    },
+  ]);
+
+  await db.insert(schema.readerPreferences).values({ userId: userA, bookFileId: primaryFileId, settings: { fontSize: 17, lineHeight: 1.6 } });
+
+  return {
+    snapshot: await loadStatefulSnapshot(db, bookId, primaryFileId),
+  };
+}
+
+async function assertStatefulUnchanged(
+  db: ScannerE2EContext['db'],
+  bookId: number,
+  primaryFileId: number,
+  expectedSnapshot: StatefulSnapshot,
+): Promise<void> {
+  const actual = await loadStatefulSnapshot(db, bookId, primaryFileId);
+  expect(actual).toEqual(expectedSnapshot);
+}
+
+async function writeScenarioReport(results: ScenarioRunResult[]): Promise<void> {
+  const reportDir = process.env.JUNIT_OUTPUT ? dirname(process.env.JUNIT_OUTPUT) : join(process.cwd(), '..', 'test-results', 'server');
+  await mkdir(reportDir, { recursive: true });
+  const reportPath = join(reportDir, 'scanner-file-ops-e2e-scenarios.json');
+  await writeFile(
+    reportPath,
+    JSON.stringify(
+      {
+        generatedAt: new Date().toISOString(),
+        total: results.length,
+        passed: results.filter((result) => result.status === 'passed').length,
+        failed: results.filter((result) => result.status === 'failed').length,
+        skipped: results.filter((result) => result.status === 'skipped').length,
+        results,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+async function runRecordedScenario(scenarioId: string, trigger: TriggerMode, results: ScenarioRunResult[], work: () => Promise<void>): Promise<void> {
+  const startedAt = Date.now();
+  try {
+    await work();
+    results.push({ id: scenarioId, trigger, status: 'passed', durationMs: Date.now() - startedAt });
+  } catch (err) {
+    results.push({
+      id: scenarioId,
+      trigger,
+      status: 'failed',
+      durationMs: Date.now() - startedAt,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    throw err;
+  }
+}
+
+describe('Scanner file operations (e2e)', () => {
+  let context: ScannerE2EContext | null = null;
+  const scenarioResults: ScenarioRunResult[] = [];
+
+  beforeAll(async () => {
+    context = await createScannerE2EContext();
+  });
+
+  afterAll(async () => {
+    await writeScenarioReport(scenarioResults);
+    if (context) {
+      await closeScannerE2EContext(context);
+    }
+  });
+
+  describe('structural scenarios', () => {
+    for (const scenario of structuralScenarios) {
+      it(
+        scenario.id,
+        async () => {
+          if (!context) throw new Error('E2E context not initialized');
+          await runStructuralScenario(context, scenario, scenarioResults);
+        },
+        SCENARIO_TIMEOUT_MS,
+      );
+    }
+  });
+
+  describe('stateful consistency scenarios', () => {
+    it(
+      'stateful-manual-delete-primary-preserves-data',
+      async () => {
+        if (!context) throw new Error('E2E context not initialized');
+
+        await runRecordedScenario('stateful-manual-delete-primary-preserves-data', 'manual', scenarioResults, async () => {
+          await resetScannerFileOpsState(context.db);
+          const fixture = await createFixtureTree([file('lib-a/Book/book.epub')], 'scanner-file-ops-stateful-manual-delete-');
+          try {
+            const requestedRootA = join(fixture.rootPath, 'lib-a');
+            await mkdir(requestedRootA, { recursive: true });
+            const rootA = await realpath(requestedRootA);
+            const library = await seedLibrary(context.db, {
+              rootPath: rootA,
+              mode: 'book_per_folder',
+              watch: false,
+              name: `scanner-file-ops-stateful-manual-delete-${randomUUID()}`,
+            });
+
+            await triggerAndWaitForLibraryScan(context, library.libraryId);
+
+            const sourceBook = await getBookByFolderPath(context.db, library.libraryId, join(rootA, 'Book'));
+            if (sourceBook.primaryFileId == null) throw new Error('Expected primary file id to be present');
+
+            const seeded = await seedStatefulData(context.db, sourceBook.id, sourceBook.primaryFileId);
+
+            await applyOperation(fixture.rootPath, { type: 'deleteFile', path: 'lib-a/Book/book.epub' });
+            await triggerAndWaitForLibraryScan(context, library.libraryId);
+
+            const sourceAfter = await getBookById(context.db, sourceBook.id);
+            expect(sourceAfter.status).toBe('missing');
+
+            await assertStatefulUnchanged(context.db, sourceBook.id, sourceBook.primaryFileId, seeded.snapshot);
+            await assertNoIntegrityViolations(context.db);
+          } finally {
+            await fixture.cleanup();
+          }
+        });
+      },
+      SCENARIO_TIMEOUT_MS,
+    );
+
+    it(
+      'stateful-manual-cross-library-move-preserves-book-identity',
+      async () => {
+        if (!context) throw new Error('E2E context not initialized');
+
+        await runRecordedScenario('stateful-manual-cross-library-move-preserves-book-identity', 'manual', scenarioResults, async () => {
+          await resetScannerFileOpsState(context.db);
+          const fixture = await createFixtureTree([file('lib-a/Book/book.epub')], 'scanner-file-ops-stateful-cross-lib-manual-');
+          try {
+            const requestedRootA = join(fixture.rootPath, 'lib-a');
+            const requestedRootB = join(fixture.rootPath, 'lib-b');
+            await mkdir(requestedRootA, { recursive: true });
+            await mkdir(requestedRootB, { recursive: true });
+            const rootA = await realpath(requestedRootA);
+            const rootB = await realpath(requestedRootB);
+
+            const sourceLibrary = await seedLibrary(context.db, {
+              rootPath: rootA,
+              mode: 'book_per_folder',
+              watch: false,
+              name: `scanner-file-ops-stateful-source-${randomUUID()}`,
+            });
+            const destinationLibrary = await seedLibrary(context.db, {
+              rootPath: rootB,
+              mode: 'book_per_folder',
+              watch: false,
+              name: `scanner-file-ops-stateful-destination-${randomUUID()}`,
+            });
+
+            await triggerAndWaitForLibraryScan(context, sourceLibrary.libraryId);
+            await triggerAndWaitForLibraryScan(context, destinationLibrary.libraryId);
+
+            const sourceBook = await getBookByFolderPath(context.db, sourceLibrary.libraryId, join(rootA, 'Book'));
+            if (sourceBook.primaryFileId == null) throw new Error('Expected source primary file id to be present');
+
+            const seeded = await seedStatefulData(context.db, sourceBook.id, sourceBook.primaryFileId);
+
+            await applyOperation(fixture.rootPath, { type: 'move', from: 'lib-a/Book/book.epub', to: 'lib-b/Inbox/book.epub' });
+
+            await triggerAndWaitForLibraryScan(context, sourceLibrary.libraryId);
+            await triggerAndWaitForLibraryScan(context, destinationLibrary.libraryId);
+
+            const movedBook = await getBookById(context.db, sourceBook.id);
+            expect(movedBook.libraryId).toBe(destinationLibrary.libraryId);
+            expect(movedBook.status).toBe('present');
+            expect(movedBook.folderPath).toBe(join(rootB, 'Inbox'));
+            expect(movedBook.primaryFileId).toBe(sourceBook.primaryFileId);
+
+            const destinationBook = await getBookByFolderPath(context.db, destinationLibrary.libraryId, join(rootB, 'Inbox'));
+            expect(destinationBook.id).toBe(sourceBook.id);
+            expect(destinationBook.status).toBe('present');
+            expect(destinationBook.primaryFileId).toBe(sourceBook.primaryFileId);
+
+            const sourceState = await loadLibraryBookState(context.db, sourceLibrary.libraryId);
+            expect(sourceState).toHaveLength(0);
+
+            await assertStatefulUnchanged(context.db, sourceBook.id, sourceBook.primaryFileId, seeded.snapshot);
+            await assertNoIntegrityViolations(context.db);
+          } finally {
+            await fixture.cleanup();
+          }
+        });
+      },
+      SCENARIO_TIMEOUT_MS,
+    );
+
+    it(
+      'stateful-watcher-cross-library-move-preserves-book-identity',
+      async () => {
+        if (!context) throw new Error('E2E context not initialized');
+
+        await runRecordedScenario('stateful-watcher-cross-library-move-preserves-book-identity', 'watcher', scenarioResults, async () => {
+          await resetScannerFileOpsState(context.db);
+          const fixture = await createFixtureTree([file('lib-a/Book/book.epub')], 'scanner-file-ops-stateful-cross-lib-watcher-');
+          let sourceLibraryId: number | null = null;
+          let destinationLibraryId: number | null = null;
+          try {
+            const requestedRootA = join(fixture.rootPath, 'lib-a');
+            const requestedRootB = join(fixture.rootPath, 'lib-b');
+            await mkdir(requestedRootA, { recursive: true });
+            await mkdir(requestedRootB, { recursive: true });
+            const rootA = await realpath(requestedRootA);
+            const rootB = await realpath(requestedRootB);
+
+            const sourceLibrary = await seedLibrary(context.db, {
+              rootPath: rootA,
+              mode: 'book_per_folder',
+              watch: false,
+              name: `scanner-file-ops-stateful-source-watcher-${randomUUID()}`,
+            });
+            sourceLibraryId = sourceLibrary.libraryId;
+            const destinationLibrary = await seedLibrary(context.db, {
+              rootPath: rootB,
+              mode: 'book_per_folder',
+              watch: false,
+              name: `scanner-file-ops-stateful-destination-watcher-${randomUUID()}`,
+            });
+            destinationLibraryId = destinationLibrary.libraryId;
+
+            await triggerAndWaitForLibraryScan(context, sourceLibrary.libraryId);
+            await triggerAndWaitForLibraryScan(context, destinationLibrary.libraryId);
+
+            const sourceBook = await getBookByFolderPath(context.db, sourceLibrary.libraryId, join(rootA, 'Book'));
+            if (sourceBook.primaryFileId == null) throw new Error('Expected source primary file id to be present');
+
+            const seeded = await seedStatefulData(context.db, sourceBook.id, sourceBook.primaryFileId);
+
+            await startLibraryWatcher(context, sourceLibrary.libraryId, [rootA]);
+            await startLibraryWatcher(context, destinationLibrary.libraryId, [rootB]);
+            await applyOperation(fixture.rootPath, { type: 'move', from: 'lib-a/Book/book.epub', to: 'lib-b/Inbox/book.epub' });
+
+            await waitForCondition(async () => {
+              const movedBook = await getBookById(context.db, sourceBook.id);
+              expect(movedBook.libraryId).toBe(destinationLibrary.libraryId);
+              expect(movedBook.status).toBe('present');
+              expect(movedBook.folderPath).toBe(join(rootB, 'Inbox'));
+              expect(movedBook.primaryFileId).toBe(sourceBook.primaryFileId);
+
+              const destinationBook = await getBookByFolderPath(context.db, destinationLibrary.libraryId, join(rootB, 'Inbox'));
+              expect(destinationBook.id).toBe(sourceBook.id);
+              expect(destinationBook.primaryFileId).toBe(sourceBook.primaryFileId);
+
+              const sourceState = await loadLibraryBookState(context.db, sourceLibrary.libraryId);
+              expect(sourceState).toHaveLength(0);
+            }, 40_000);
+
+            await assertStatefulUnchanged(context.db, sourceBook.id, sourceBook.primaryFileId, seeded.snapshot);
+            await assertNoIntegrityViolations(context.db);
+          } finally {
+            if (sourceLibraryId != null) {
+              await stopLibraryWatcher(context, sourceLibraryId);
+            }
+            if (destinationLibraryId != null) {
+              await stopLibraryWatcher(context, destinationLibraryId);
+            }
+            await fixture.cleanup();
+          }
+        });
+      },
+      SCENARIO_TIMEOUT_MS,
+    );
+
+    it(
+      'stateful-watcher-rename-folder-preserves-data',
+      async () => {
+        if (!context) throw new Error('E2E context not initialized');
+
+        await runRecordedScenario('stateful-watcher-rename-folder-preserves-data', 'watcher', scenarioResults, async () => {
+          await resetScannerFileOpsState(context.db);
+          const fixture = await createFixtureTree([file('lib-a/Old/book.epub')], 'scanner-file-ops-stateful-watcher-rename-');
+          let libraryId: number | null = null;
+          try {
+            const requestedRootA = join(fixture.rootPath, 'lib-a');
+            await mkdir(requestedRootA, { recursive: true });
+            const rootA = await realpath(requestedRootA);
+            const library = await seedLibrary(context.db, {
+              rootPath: rootA,
+              mode: 'book_per_folder',
+              watch: false,
+              name: `scanner-file-ops-stateful-watcher-rename-${randomUUID()}`,
+            });
+            libraryId = library.libraryId;
+
+            await triggerAndWaitForLibraryScan(context, library.libraryId);
+
+            const sourceBook = await getBookByFolderPath(context.db, library.libraryId, join(rootA, 'Old'));
+            if (sourceBook.primaryFileId == null) throw new Error('Expected source primary file id to be present');
+
+            const seeded = await seedStatefulData(context.db, sourceBook.id, sourceBook.primaryFileId);
+
+            await startLibraryWatcher(context, library.libraryId, [rootA]);
+            await applyOperation(fixture.rootPath, { type: 'move', from: 'lib-a/Old', to: 'lib-a/New' });
+
+            await waitForCondition(async () => {
+              const book = await getBookById(context.db, sourceBook.id);
+              expect(book.status).toBe('present');
+              expect(book.folderPath).toBe(join(rootA, 'New'));
+            }, 40_000);
+
+            await assertStatefulUnchanged(context.db, sourceBook.id, sourceBook.primaryFileId, seeded.snapshot);
+            await assertNoIntegrityViolations(context.db);
+          } finally {
+            if (libraryId != null) {
+              await stopLibraryWatcher(context, libraryId);
+            }
+            await fixture.cleanup();
+          }
+        });
+      },
+      SCENARIO_TIMEOUT_MS,
+    );
+
+    it(
+      'stateful-watcher-delete-then-restore-preserves-data',
+      async () => {
+        if (!context) throw new Error('E2E context not initialized');
+
+        await runRecordedScenario('stateful-watcher-delete-then-restore-preserves-data', 'watcher', scenarioResults, async () => {
+          await resetScannerFileOpsState(context.db);
+          const fixture = await createFixtureTree([file('lib-a/Book/book.epub')], 'scanner-file-ops-stateful-watcher-delete-restore-');
+          let libraryId: number | null = null;
+          try {
+            const requestedRootA = join(fixture.rootPath, 'lib-a');
+            await mkdir(requestedRootA, { recursive: true });
+            const rootA = await realpath(requestedRootA);
+            const library = await seedLibrary(context.db, {
+              rootPath: rootA,
+              mode: 'book_per_folder',
+              watch: false,
+              name: `scanner-file-ops-stateful-watcher-delete-restore-${randomUUID()}`,
+            });
+            libraryId = library.libraryId;
+
+            await triggerAndWaitForLibraryScan(context, library.libraryId);
+
+            const sourceBook = await getBookByFolderPath(context.db, library.libraryId, join(rootA, 'Book'));
+            if (sourceBook.primaryFileId == null) throw new Error('Expected source primary file id to be present');
+
+            const seeded = await seedStatefulData(context.db, sourceBook.id, sourceBook.primaryFileId);
+
+            await startLibraryWatcher(context, library.libraryId, [rootA]);
+
+            await applyOperation(fixture.rootPath, { type: 'deleteFile', path: 'lib-a/Book/book.epub' });
+
+            await waitForCondition(async () => {
+              const book = await getBookById(context.db, sourceBook.id);
+              expect(book.status).toBe('missing');
+            }, 40_000);
+
+            await applyOperation(fixture.rootPath, { type: 'writeFile', path: 'lib-a/Book/book.epub' });
+
+            await waitForCondition(async () => {
+              const book = await getBookById(context.db, sourceBook.id);
+              expect(book.status).toBe('present');
+            }, 40_000);
+
+            await assertStatefulUnchanged(context.db, sourceBook.id, sourceBook.primaryFileId, seeded.snapshot);
+            await assertNoIntegrityViolations(context.db);
+          } finally {
+            if (libraryId != null) {
+              await stopLibraryWatcher(context, libraryId);
+            }
+            await fixture.cleanup();
+          }
+        });
+      },
+      SCENARIO_TIMEOUT_MS,
+    );
+  });
+});
diff --git a/server/test/scanner.e2e-spec.ts b/server/test/scanner.e2e-spec.ts
new file mode 100644
index 000000000..57afa2c0f
--- /dev/null
+++ b/server/test/scanner.e2e-spec.ts
@@ -0,0 +1,474 @@
+vi.mock('../src/modules/scanner/lib/stability', () => ({
+  waitForStability: vi.fn().mockResolvedValue(undefined),
+}));
+
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
+
+import type { FixtureEntry } from './e2e/scanner-fixture-builder';
+import { createFixtureTree, file } from './e2e/scanner-fixture-builder';
+import {
+  closeScannerE2EContext,
+  createScannerE2EContext,
+  loadLibraryBookState,
+  seedLibrary,
+  triggerLibraryScan,
+  waitForScanCompletion,
+  type LibraryBookState,
+  type ScannerE2EContext,
+} from './e2e/scanner-harness';
+
+type OrganizationMode = 'book_per_file' | 'book_per_folder';
+
+interface ExpectedBook {
+  folderPath: string;
+  filePaths: string[];
+  primaryPath?: string | null;
+  status?: 'present' | 'missing';
+}
+
+interface ScannerScenario {
+  id: string;
+  mode: OrganizationMode;
+  entries: FixtureEntry[];
+  expected: ExpectedBook[];
+  allowedFormats?: string[];
+  excludePatterns?: string[];
+}
+
+interface ScenarioRunResult {
+  id: string;
+  mode: OrganizationMode;
+  status: 'passed' | 'failed';
+  durationMs: number;
+  error?: string;
+}
+
+const SCENARIO_TIMEOUT_MS = 60_000;
+
+const bookPerFolderScenarios: ScannerScenario[] = [
+  {
+    id: 'book-per-folder-flat-root-file',
+    mode: 'book_per_folder',
+    entries: [file('book.epub')],
+    expected: [{ folderPath: 'book.epub', filePaths: ['book.epub'], primaryPath: 'book.epub' }],
+  },
+  {
+    id: 'book-per-folder-mixed-root-and-folder',
+    mode: 'book_per_folder',
+    entries: [file('root.pdf'), file('Author/Book/book.epub')],
+    expected: [
+      { folderPath: 'root.pdf', filePaths: ['root.pdf'], primaryPath: 'root.pdf' },
+      { folderPath: 'Author/Book', filePaths: ['Author/Book/book.epub'], primaryPath: 'Author/Book/book.epub' },
+    ],
+  },
+  {
+    id: 'book-per-folder-multi-format-folder-and-root-stray',
+    mode: 'book_per_folder',
+    entries: [file('Series/Book/book.epub'), file('Series/Book/book.mobi'), file('Series/Book/cover.jpg'), file('stray.cbz')],
+    expected: [
+      {
+        folderPath: 'Series/Book',
+        filePaths: ['Series/Book/book.epub', 'Series/Book/book.mobi', 'Series/Book/cover.jpg'],
+        primaryPath: 'Series/Book/book.epub',
+      },
+      { folderPath: 'stray.cbz', filePaths: ['stray.cbz'], primaryPath: 'stray.cbz' },
+    ],
+  },
+  {
+    id: 'book-per-folder-audiobook-multipart-folder',
+    mode: 'book_per_folder',
+    entries: [file('Audio/track-1.mp3'), file('Audio/track-2.mp3'), file('Audio/cover.jpg')],
+    expected: [
+      {
+        folderPath: 'Audio',
+        filePaths: ['Audio/cover.jpg', 'Audio/track-1.mp3', 'Audio/track-2.mp3'],
+        primaryPath: 'Audio/track-1.mp3',
+      },
+    ],
+  },
+  {
+    id: 'book-per-folder-disc-folder-flattening',
+    mode: 'book_per_folder',
+    entries: [file('AudioBook/CD 1/01.mp3'), file('AudioBook/Disc 2/02.mp3'), file('AudioBook/cover.jpg')],
+    expected: [
+      {
+        folderPath: 'AudioBook',
+        filePaths: ['AudioBook/CD 1/01.mp3', 'AudioBook/Disc 2/02.mp3', 'AudioBook/cover.jpg'],
+        primaryPath: 'AudioBook/CD 1/01.mp3',
+      },
+    ],
+  },
+  {
+    id: 'book-per-folder-ebook-with-stem-audio-subfolder',
+    mode: 'book_per_folder',
+    entries: [file('TheBook/TheBook.epub'), file('TheBook/TheBook/01.mp3'), file('TheBook/TheBook/02.mp3')],
+    expected: [
+      {
+        folderPath: 'TheBook',
+        filePaths: ['TheBook/TheBook.epub', 'TheBook/TheBook/01.mp3', 'TheBook/TheBook/02.mp3'],
+        primaryPath: 'TheBook/TheBook.epub',
+      },
+    ],
+  },
+  {
+    id: 'book-per-folder-root-stem-audio-not-flattened',
+    mode: 'book_per_folder',
+    entries: [file('BookTitle.epub'), file('BookTitle/01.mp3'), file('BookTitle/02.mp3')],
+    expected: [
+      { folderPath: 'BookTitle.epub', filePaths: ['BookTitle.epub'], primaryPath: 'BookTitle.epub' },
+      { folderPath: 'BookTitle', filePaths: ['BookTitle/01.mp3', 'BookTitle/02.mp3'], primaryPath: 'BookTitle/01.mp3' },
+    ],
+  },
+  {
+    id: 'book-per-folder-hidden-files-and-folders-ignored',
+    mode: 'book_per_folder',
+    entries: [file('.hidden/ghost.epub'), file('.root-hidden.epub'), file('Visible/book.epub')],
+    expected: [{ folderPath: 'Visible', filePaths: ['Visible/book.epub'], primaryPath: 'Visible/book.epub' }],
+  },
+  {
+    id: 'book-per-folder-exclude-patterns',
+    mode: 'book_per_folder',
+    entries: [file('skip-folder/book.epub'), file('keep-folder/book.epub'), file('keep-folder/cover.jpg')],
+    excludePatterns: ['skip*'],
+    expected: [{ folderPath: 'keep-folder', filePaths: ['keep-folder/book.epub', 'keep-folder/cover.jpg'], primaryPath: 'keep-folder/book.epub' }],
+  },
+  {
+    id: 'book-per-folder-allowed-formats',
+    mode: 'book_per_folder',
+    entries: [file('book.epub'), file('book.pdf')],
+    allowedFormats: ['epub'],
+    expected: [{ folderPath: 'book.epub', filePaths: ['book.epub'], primaryPath: 'book.epub' }],
+  },
+  {
+    id: 'book-per-folder-zero-byte-content-file-skipped',
+    mode: 'book_per_folder',
+    entries: [file('zero.epub', '')],
+    expected: [{ folderPath: 'zero.epub', filePaths: [], primaryPath: null }],
+  },
+  {
+    id: 'book-per-folder-no-primary-files',
+    mode: 'book_per_folder',
+    entries: [file('Only/cover.jpg'), file('Only/book.opf')],
+    expected: [],
+  },
+  {
+    id: 'book-per-folder-deep-nested-book-folder',
+    mode: 'book_per_folder',
+    entries: [file('A/B/C/book.epub')],
+    expected: [{ folderPath: 'A/B/C', filePaths: ['A/B/C/book.epub'], primaryPath: 'A/B/C/book.epub' }],
+  },
+  {
+    id: 'book-per-folder-same-filename-different-authors',
+    mode: 'book_per_folder',
+    entries: [file('Author One/Shared/book.epub'), file('Author Two/Shared/book.epub')],
+    expected: [
+      { folderPath: 'Author One/Shared', filePaths: ['Author One/Shared/book.epub'], primaryPath: 'Author One/Shared/book.epub' },
+      { folderPath: 'Author Two/Shared', filePaths: ['Author Two/Shared/book.epub'], primaryPath: 'Author Two/Shared/book.epub' },
+    ],
+  },
+  {
+    id: 'book-per-folder-disc-name-variants-flattened',
+    mode: 'book_per_folder',
+    entries: [file('Saga/Disk03/03.mp3'), file('Saga/PartA/04.mp3'), file('Saga/SideB/05.mp3'), file('Saga/front.jpg')],
+    expected: [
+      {
+        folderPath: 'Saga',
+        filePaths: ['Saga/Disk03/03.mp3', 'Saga/PartA/04.mp3', 'Saga/SideB/05.mp3', 'Saga/front.jpg'],
+        primaryPath: 'Saga/Disk03/03.mp3',
+      },
+    ],
+  },
+  {
+    id: 'book-per-folder-stem-subfolder-case-mismatch-no-merge',
+    mode: 'book_per_folder',
+    entries: [file('Novel/Book.epub'), file('Novel/book/01.mp3'), file('Novel/book/02.mp3')],
+    expected: [
+      { folderPath: 'Novel', filePaths: ['Novel/Book.epub'], primaryPath: 'Novel/Book.epub' },
+      { folderPath: 'Novel/book', filePaths: ['Novel/book/01.mp3', 'Novel/book/02.mp3'], primaryPath: 'Novel/book/01.mp3' },
+    ],
+  },
+  {
+    id: 'book-per-folder-stem-subfolder-with-disc-flattening',
+    mode: 'book_per_folder',
+    entries: [file('Title/Title.epub'), file('Title/Title/CD 1/01.mp3'), file('Title/Title/Disc 2/02.mp3'), file('Title/cover.jpg')],
+    expected: [
+      {
+        folderPath: 'Title',
+        filePaths: ['Title/Title.epub', 'Title/Title/CD 1/01.mp3', 'Title/Title/Disc 2/02.mp3', 'Title/cover.jpg'],
+        primaryPath: 'Title/Title.epub',
+      },
+    ],
+  },
+  {
+    id: 'book-per-folder-root-multi-format-files-remain-separate',
+    mode: 'book_per_folder',
+    entries: [file('book.epub'), file('book.mobi')],
+    expected: [
+      { folderPath: 'book.epub', filePaths: ['book.epub'], primaryPath: 'book.epub' },
+      { folderPath: 'book.mobi', filePaths: ['book.mobi'], primaryPath: 'book.mobi' },
+    ],
+  },
+  {
+    id: 'book-per-folder-multi-book-single-folder-coalesced',
+    mode: 'book_per_folder',
+    entries: [file('Anthology/Book One.epub'), file('Anthology/Book Two.epub'), file('Anthology/cover.jpg')],
+    expected: [{ folderPath: 'Anthology', filePaths: ['Anthology/Book One.epub', 'Anthology/Book Two.epub', 'Anthology/cover.jpg'] }],
+  },
+  {
+    id: 'book-per-folder-allowed-formats-audio-filter',
+    mode: 'book_per_folder',
+    entries: [file('Audio/book.mp3'), file('Audio/book.m4b'), file('Audio/cover.jpg')],
+    allowedFormats: ['m4b'],
+    expected: [{ folderPath: 'Audio', filePaths: ['Audio/book.m4b', 'Audio/cover.jpg'], primaryPath: 'Audio/book.m4b' }],
+  },
+  {
+    id: 'book-per-folder-exclude-exact-root-filename',
+    mode: 'book_per_folder',
+    entries: [file('skip.epub'), file('Keep/book.epub')],
+    excludePatterns: ['skip.epub'],
+    expected: [{ folderPath: 'Keep', filePaths: ['Keep/book.epub'], primaryPath: 'Keep/book.epub' }],
+  },
+  {
+    id: 'book-per-folder-uppercase-extensions',
+    mode: 'book_per_folder',
+    entries: [file('Caps/BOOK.EPUB'), file('Caps/COVER.JPG')],
+    expected: [{ folderPath: 'Caps', filePaths: ['Caps/BOOK.EPUB', 'Caps/COVER.JPG'], primaryPath: 'Caps/BOOK.EPUB' }],
+  },
+  {
+    id: 'book-per-folder-non-disc-similar-folder-not-flattened',
+    mode: 'book_per_folder',
+    entries: [file('AudioBook/Discography/01.mp3'), file('AudioBook/cover.jpg')],
+    expected: [{ folderPath: 'AudioBook/Discography', filePaths: ['AudioBook/Discography/01.mp3'], primaryPath: 'AudioBook/Discography/01.mp3' }],
+  },
+];
+
+const bookPerFileScenarios: ScannerScenario[] = [
+  {
+    id: 'book-per-file-multiple-content-files',
+    mode: 'book_per_file',
+    entries: [file('Series/book1.epub'), file('Series/book2.epub'), file('Series/book3.mobi'), file('Series/cover.jpg')],
+    expected: [
+      { folderPath: 'Series/book1.epub', filePaths: ['Series/book1.epub'], primaryPath: 'Series/book1.epub' },
+      { folderPath: 'Series/book2.epub', filePaths: ['Series/book2.epub'], primaryPath: 'Series/book2.epub' },
+      { folderPath: 'Series/book3.mobi', filePaths: ['Series/book3.mobi'], primaryPath: 'Series/book3.mobi' },
+    ],
+  },
+  {
+    id: 'book-per-file-audio-parts',
+    mode: 'book_per_file',
+    entries: [file('Audio/01.mp3'), file('Audio/02.mp3')],
+    expected: [
+      { folderPath: 'Audio/01.mp3', filePaths: ['Audio/01.mp3'], primaryPath: 'Audio/01.mp3' },
+      { folderPath: 'Audio/02.mp3', filePaths: ['Audio/02.mp3'], primaryPath: 'Audio/02.mp3' },
+    ],
+  },
+  {
+    id: 'book-per-file-ignore-non-content',
+    mode: 'book_per_file',
+    entries: [file('Book/cover.jpg'), file('Book/book.epub')],
+    expected: [{ folderPath: 'Book/book.epub', filePaths: ['Book/book.epub'], primaryPath: 'Book/book.epub' }],
+  },
+  {
+    id: 'book-per-file-allowed-formats-and-excludes',
+    mode: 'book_per_file',
+    entries: [file('keep.epub'), file('keep.pdf'), file('skip-folder/skip.epub')],
+    allowedFormats: ['epub'],
+    excludePatterns: ['skip*'],
+    expected: [{ folderPath: 'keep.epub', filePaths: ['keep.epub'], primaryPath: 'keep.epub' }],
+  },
+  {
+    id: 'book-per-file-deep-root-mix',
+    mode: 'book_per_file',
+    entries: [file('root.epub'), file('A/B/C/book.pdf'), file('A/B/C/cover.jpg')],
+    expected: [
+      { folderPath: 'root.epub', filePaths: ['root.epub'], primaryPath: 'root.epub' },
+      { folderPath: 'A/B/C/book.pdf', filePaths: ['A/B/C/book.pdf'], primaryPath: 'A/B/C/book.pdf' },
+    ],
+  },
+  {
+    id: 'book-per-file-disc-subfolders-not-grouped',
+    mode: 'book_per_file',
+    entries: [file('Saga/CD 1/01.mp3'), file('Saga/Disc 2/02.mp3'), file('Saga/cover.jpg')],
+    expected: [
+      { folderPath: 'Saga/CD 1/01.mp3', filePaths: ['Saga/CD 1/01.mp3'], primaryPath: 'Saga/CD 1/01.mp3' },
+      { folderPath: 'Saga/Disc 2/02.mp3', filePaths: ['Saga/Disc 2/02.mp3'], primaryPath: 'Saga/Disc 2/02.mp3' },
+    ],
+  },
+  {
+    id: 'book-per-file-uppercase-extensions',
+    mode: 'book_per_file',
+    entries: [file('Novel/Book.EPUB'), file('Novel/Book.PDF')],
+    expected: [
+      { folderPath: 'Novel/Book.EPUB', filePaths: ['Novel/Book.EPUB'], primaryPath: 'Novel/Book.EPUB' },
+      { folderPath: 'Novel/Book.PDF', filePaths: ['Novel/Book.PDF'], primaryPath: 'Novel/Book.PDF' },
+    ],
+  },
+  {
+    id: 'book-per-file-exclude-exact-filename',
+    mode: 'book_per_file',
+    entries: [file('keep.epub'), file('skip.epub')],
+    excludePatterns: ['skip.epub'],
+    expected: [{ folderPath: 'keep.epub', filePaths: ['keep.epub'], primaryPath: 'keep.epub' }],
+  },
+  {
+    id: 'book-per-file-allowed-formats-case-insensitive',
+    mode: 'book_per_file',
+    entries: [file('keep.EPUB'), file('drop.PDF')],
+    allowedFormats: ['epub'],
+    expected: [{ folderPath: 'keep.EPUB', filePaths: ['keep.EPUB'], primaryPath: 'keep.EPUB' }],
+  },
+  {
+    id: 'book-per-file-hidden-and-no-extension-ignored',
+    mode: 'book_per_file',
+    entries: [file('.hidden/ghost.epub'), file('visible/README'), file('visible/book.mobi')],
+    expected: [{ folderPath: 'visible/book.mobi', filePaths: ['visible/book.mobi'], primaryPath: 'visible/book.mobi' }],
+  },
+  {
+    id: 'book-per-file-root-and-nested-same-name',
+    mode: 'book_per_file',
+    entries: [file('book.epub'), file('Series/book.epub')],
+    expected: [
+      { folderPath: 'book.epub', filePaths: ['book.epub'], primaryPath: 'book.epub' },
+      { folderPath: 'Series/book.epub', filePaths: ['Series/book.epub'], primaryPath: 'Series/book.epub' },
+    ],
+  },
+  {
+    id: 'book-per-file-zero-byte-file-skipped',
+    mode: 'book_per_file',
+    entries: [file('empty.epub', ''), file('valid.epub')],
+    expected: [
+      { folderPath: 'empty.epub', filePaths: [], primaryPath: null },
+      { folderPath: 'valid.epub', filePaths: ['valid.epub'], primaryPath: 'valid.epub' },
+    ],
+  },
+];
+
+function toAbsolutePath(rootPath: string, relativePath: string): string {
+  return join(rootPath, relativePath);
+}
+
+function assertScenarioOutcome(rootPath: string, expected: ExpectedBook[], actual: LibraryBookState[]): void {
+  const resolvedExpected = expected.map((book) => ({
+    folderPath: toAbsolutePath(rootPath, book.folderPath),
+    status: book.status ?? 'present',
+    primaryPath: book.primaryPath === undefined ? undefined : book.primaryPath === null ? null : toAbsolutePath(rootPath, book.primaryPath),
+    filePaths: book.filePaths.map((path) => toAbsolutePath(rootPath, path)).sort(),
+  }));
+
+  const expectedFolderPaths = resolvedExpected.map((book) => book.folderPath).sort();
+  const actualFolderPaths = actual.map((book) => book.folderPath).sort();
+  expect(actualFolderPaths).toEqual(expectedFolderPaths);
+
+  const actualByFolderPath = new Map(actual.map((book) => [book.folderPath, book]));
+
+  for (const expectedBook of resolvedExpected) {
+    const actualBook = actualByFolderPath.get(expectedBook.folderPath);
+    expect(actualBook).toBeDefined();
+    expect(actualBook!.status).toBe(expectedBook.status);
+    expect(actualBook!.filePaths).toEqual(expectedBook.filePaths);
+    if (expectedBook.primaryPath !== undefined) {
+      expect(actualBook!.primaryPath).toBe(expectedBook.primaryPath);
+    }
+  }
+}
+
+async function runScenario(context: ScannerE2EContext, scenario: ScannerScenario, results: ScenarioRunResult[]): Promise<void> {
+  const fixture = await createFixtureTree(scenario.entries, `scanner-e2e-${scenario.id}-`);
+  const startedAt = Date.now();
+
+  try {
+    const { libraryId } = await seedLibrary(context.db, {
+      rootPath: fixture.rootPath,
+      mode: scenario.mode,
+      allowedFormats: scenario.allowedFormats,
+      excludePatterns: scenario.excludePatterns,
+    });
+
+    const jobId = await triggerLibraryScan(context, libraryId);
+    await waitForScanCompletion(context.db, jobId);
+
+    const actual = await loadLibraryBookState(context.db, libraryId);
+    assertScenarioOutcome(fixture.rootPath, scenario.expected, actual);
+
+    results.push({
+      id: scenario.id,
+      mode: scenario.mode,
+      status: 'passed',
+      durationMs: Date.now() - startedAt,
+    });
+  } catch (err) {
+    results.push({
+      id: scenario.id,
+      mode: scenario.mode,
+      status: 'failed',
+      durationMs: Date.now() - startedAt,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    throw err;
+  } finally {
+    await fixture.cleanup();
+  }
+}
+
+async function writeScenarioReport(results: ScenarioRunResult[]): Promise<void> {
+  const reportDir = process.env.JUNIT_OUTPUT ? dirname(process.env.JUNIT_OUTPUT) : join(process.cwd(), '..', 'test-results', 'server');
+  await mkdir(reportDir, { recursive: true });
+  const reportPath = join(reportDir, 'scanner-e2e-scenarios.json');
+  await writeFile(
+    reportPath,
+    JSON.stringify(
+      {
+        generatedAt: new Date().toISOString(),
+        total: results.length,
+        passed: results.filter((result) => result.status === 'passed').length,
+        failed: results.filter((result) => result.status === 'failed').length,
+        results,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+describe('Scanner structures (e2e)', () => {
+  let context: ScannerE2EContext | null = null;
+  const scenarioResults: ScenarioRunResult[] = [];
+
+  beforeAll(async () => {
+    context = await createScannerE2EContext();
+  });
+
+  afterAll(async () => {
+    await writeScenarioReport(scenarioResults);
+    if (context) {
+      await closeScannerE2EContext(context);
+    }
+  });
+
+  describe('organizationMode=book_per_folder', () => {
+    for (const scenario of bookPerFolderScenarios) {
+      it(
+        scenario.id,
+        async () => {
+          if (!context) throw new Error('E2E context not initialized');
+          await runScenario(context, scenario, scenarioResults);
+        },
+        SCENARIO_TIMEOUT_MS,
+      );
+    }
+  });
+
+  describe('organizationMode=book_per_file', () => {
+    for (const scenario of bookPerFileScenarios) {
+      it(
+        scenario.id,
+        async () => {
+          if (!context) throw new Error('E2E context not initialized');
+          await runScenario(context, scenario, scenarioResults);
+        },
+        SCENARIO_TIMEOUT_MS,
+      );
+    }
+  });
+});
diff --git a/test-results/server/scanner-e2e-junit.xml b/test-results/server/scanner-e2e-junit.xml
new file mode 100644
index 000000000..115a5a34b
--- /dev/null
+++ b/test-results/server/scanner-e2e-junit.xml
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<testsuites name="vitest tests" tests="35" failures="0" errors="0" time="4.7548795">
+    <testsuite name="test/scanner.e2e-spec.ts" timestamp="2026-04-15T03:30:47.710Z" hostname="DC-KJ3DT4LQPW.local" tests="35" failures="0" errors="0" skipped="0" time="4.7548795">
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-flat-root-file" time="0.121739833">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-mixed-root-and-folder" time="0.129137875">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-multi-format-folder-and-root-stray" time="0.128462708">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-audiobook-multipart-folder" time="0.124288667">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-disc-folder-flattening" time="0.125028375">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-ebook-with-stem-audio-subfolder" time="0.12772325">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-root-stem-audio-not-flattened" time="0.135436417">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-hidden-files-and-folders-ignored" time="0.126640375">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-exclude-patterns" time="0.126519708">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-allowed-formats" time="0.123326667">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-zero-byte-content-file-skipped" time="0.123150792">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-no-primary-files" time="0.118748583">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-deep-nested-book-folder" time="0.122631834">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-same-filename-different-authors" time="0.126866875">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-disc-name-variants-flattened" time="0.12586425">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-stem-subfolder-case-mismatch-no-merge" time="0.126321">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-stem-subfolder-with-disc-flattening" time="0.122238708">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-root-multi-format-files-remain-separate" time="0.118935375">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-multi-book-single-folder-coalesced" time="0.113775166">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-allowed-formats-audio-filter" time="0.1125685">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-exclude-exact-root-filename" time="0.118648125">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-uppercase-extensions" time="0.119853458">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_folder &gt; book-per-folder-non-disc-similar-folder-not-flattened" time="0.131077875">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-multiple-content-files" time="0.123768959">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-audio-parts" time="0.120098584">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-ignore-non-content" time="0.130401459">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-allowed-formats-and-excludes" time="0.132419792">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-deep-root-mix" time="0.132637709">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-disc-subfolders-not-grouped" time="0.126081375">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-uppercase-extensions" time="0.118420667">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-exclude-exact-filename" time="0.119933458">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-allowed-formats-case-insensitive" time="0.121673791">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-hidden-and-no-extension-ignored" time="0.118652625">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-root-and-nested-same-name" time="0.114143459">
+        </testcase>
+        <testcase classname="test/scanner.e2e-spec.ts" name="Scanner structures (e2e) &gt; organizationMode=book_per_file &gt; book-per-file-zero-byte-file-skipped" time="0.117714958">
+        </testcase>
+    </testsuite>
+</testsuites>
diff --git a/test-results/server/scanner-e2e-scenarios.json b/test-results/server/scanner-e2e-scenarios.json
new file mode 100644
index 000000000..395577f7e
--- /dev/null
+++ b/test-results/server/scanner-e2e-scenarios.json
@@ -0,0 +1,218 @@
+{
+  "generatedAt": "2026-04-15T03:30:47.698Z",
+  "total": 35,
+  "passed": 35,
+  "failed": 0,
+  "results": [
+    {
+      "id": "book-per-folder-flat-root-file",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 119
+    },
+    {
+      "id": "book-per-folder-mixed-root-and-folder",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 126
+    },
+    {
+      "id": "book-per-folder-multi-format-folder-and-root-stray",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 124
+    },
+    {
+      "id": "book-per-folder-audiobook-multipart-folder",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 121
+    },
+    {
+      "id": "book-per-folder-disc-folder-flattening",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 120
+    },
+    {
+      "id": "book-per-folder-ebook-with-stem-audio-subfolder",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 123
+    },
+    {
+      "id": "book-per-folder-root-stem-audio-not-flattened",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 123
+    },
+    {
+      "id": "book-per-folder-hidden-files-and-folders-ignored",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 124
+    },
+    {
+      "id": "book-per-folder-exclude-patterns",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 123
+    },
+    {
+      "id": "book-per-folder-allowed-formats",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 121
+    },
+    {
+      "id": "book-per-folder-zero-byte-content-file-skipped",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 121
+    },
+    {
+      "id": "book-per-folder-no-primary-files",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 115
+    },
+    {
+      "id": "book-per-folder-deep-nested-book-folder",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 120
+    },
+    {
+      "id": "book-per-folder-same-filename-different-authors",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 124
+    },
+    {
+      "id": "book-per-folder-disc-name-variants-flattened",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 121
+    },
+    {
+      "id": "book-per-folder-stem-subfolder-case-mismatch-no-merge",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 122
+    },
+    {
+      "id": "book-per-folder-stem-subfolder-with-disc-flattening",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 116
+    },
+    {
+      "id": "book-per-folder-root-multi-format-files-remain-separate",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 117
+    },
+    {
+      "id": "book-per-folder-multi-book-single-folder-coalesced",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 111
+    },
+    {
+      "id": "book-per-folder-allowed-formats-audio-filter",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 110
+    },
+    {
+      "id": "book-per-folder-exclude-exact-root-filename",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 112
+    },
+    {
+      "id": "book-per-folder-uppercase-extensions",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 115
+    },
+    {
+      "id": "book-per-folder-non-disc-similar-folder-not-flattened",
+      "mode": "book_per_folder",
+      "status": "passed",
+      "durationMs": 126
+    },
+    {
+      "id": "book-per-file-multiple-content-files",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 116
+    },
+    {
+      "id": "book-per-file-audio-parts",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 116
+    },
+    {
+      "id": "book-per-file-ignore-non-content",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 125
+    },
+    {
+      "id": "book-per-file-allowed-formats-and-excludes",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 128
+    },
+    {
+      "id": "book-per-file-deep-root-mix",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 128
+    },
+    {
+      "id": "book-per-file-disc-subfolders-not-grouped",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 121
+    },
+    {
+      "id": "book-per-file-uppercase-extensions",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 116
+    },
+    {
+      "id": "book-per-file-exclude-exact-filename",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 118
+    },
+    {
+      "id": "book-per-file-allowed-formats-case-insensitive",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 118
+    },
+    {
+      "id": "book-per-file-hidden-and-no-extension-ignored",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 113
+    },
+    {
+      "id": "book-per-file-root-and-nested-same-name",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 112
+    },
+    {
+      "id": "book-per-file-zero-byte-file-skipped",
+      "mode": "book_per_file",
+      "status": "passed",
+      "durationMs": 112
+    }
+  ]
+}
\ No newline at end of file
diff --git a/test-results/server/scanner-file-ops-e2e-junit.xml b/test-results/server/scanner-file-ops-e2e-junit.xml
new file mode 100644
index 000000000..f16e836f1
--- /dev/null
+++ b/test-results/server/scanner-file-ops-e2e-junit.xml
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<testsuites name="vitest tests" tests="39" failures="0" errors="0" time="37.268869625">
+    <testsuite name="test/scanner-file-ops.e2e-spec.ts" timestamp="2026-04-15T03:31:40.314Z" hostname="DC-KJ3DT4LQPW.local" tests="39" failures="0" errors="0" skipped="0" time="37.268869625">
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-delete-primary-file-marks-missing" time="0.294578333">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-delete-folder-marks-only-removed-book-missing" time="0.3128125">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-rename-file-in-place" time="0.294205792">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-rename-folder" time="0.294784667">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-move-root-file-into-subfolder" time="0.30047175">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-move-subfolder-file-to-root" time="0.304838667">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-cross-library-file-move" time="0.524123875">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-cross-library-folder-move" time="0.506195334">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-multi-step-churn" time="0.294776084">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-book-per-file-delete-and-move" time="0.294187041">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-move-into-existing-folder-merges" time="0.295670708">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-cross-library-move-into-existing-folder-merges" time="0.539346042">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-delete-and-recreate-same-path" time="0.282088959">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-delete-and-recreate-folder-with-new-file" time="0.26758125">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-book-per-file-folder-move-multi-file" time="0.245308375">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; manual-cross-library-move-then-reseed-source" time="0.514633208">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-delete-primary-file-marks-missing" time="0.765211042">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-delete-folder" time="0.791121958">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-rename-file-in-place" time="0.781976542">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-rename-folder" time="0.796244">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-move-root-file-into-subfolder" time="3.918478333">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-move-subfolder-file-to-root" time="3.886523458">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-cross-library-file-move" time="0.8804715">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-cross-library-folder-move" time="0.881713208">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-case-only-file-rename" time="0.781255667">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-non-content-file-creates-ignored" time="0.161706292">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-non-content-file-delete-ignored" time="0.155078375">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-book-per-file-delete-then-restore" time="1.693462125">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-move-into-existing-folder-merges" time="3.746106125">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-delete-and-recreate-same-path-within-debounce" time="0.134310834">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-delete-and-recreate-folder-with-new-file" time="1.686218333">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-cross-library-move-then-reseed-source" time="4.8905555">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-create-then-delete-new-path-within-debounce" time="0.171457541">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; structural scenarios &gt; watcher-book-per-file-cross-library-folder-move-multi-file" time="0.929455833">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; stateful consistency scenarios &gt; stateful-manual-delete-primary-preserves-data" time="0.286941625">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; stateful consistency scenarios &gt; stateful-manual-cross-library-move-preserves-book-identity" time="0.579881375">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; stateful consistency scenarios &gt; stateful-watcher-cross-library-move-preserves-book-identity" time="0.976622459">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; stateful consistency scenarios &gt; stateful-watcher-rename-folder-preserves-data" time="0.871528084">
+        </testcase>
+        <testcase classname="test/scanner-file-ops.e2e-spec.ts" name="Scanner file operations (e2e) &gt; stateful consistency scenarios &gt; stateful-watcher-delete-then-restore-preserves-data" time="1.502913459">
+        </testcase>
+    </testsuite>
+</testsuites>
diff --git a/test-results/server/scanner-file-ops-e2e-scenarios.json b/test-results/server/scanner-file-ops-e2e-scenarios.json
new file mode 100644
index 000000000..1d395c358
--- /dev/null
+++ b/test-results/server/scanner-file-ops-e2e-scenarios.json
@@ -0,0 +1,243 @@
+{
+  "generatedAt": "2026-04-15T03:31:40.294Z",
+  "total": 39,
+  "passed": 39,
+  "failed": 0,
+  "skipped": 0,
+  "results": [
+    {
+      "id": "manual-delete-primary-file-marks-missing",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 288
+    },
+    {
+      "id": "manual-delete-folder-marks-only-removed-book-missing",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 305
+    },
+    {
+      "id": "manual-rename-file-in-place",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 288
+    },
+    {
+      "id": "manual-rename-folder",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 290
+    },
+    {
+      "id": "manual-move-root-file-into-subfolder",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 294
+    },
+    {
+      "id": "manual-move-subfolder-file-to-root",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 300
+    },
+    {
+      "id": "manual-cross-library-file-move",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 517
+    },
+    {
+      "id": "manual-cross-library-folder-move",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 499
+    },
+    {
+      "id": "manual-multi-step-churn",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 287
+    },
+    {
+      "id": "manual-book-per-file-delete-and-move",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 285
+    },
+    {
+      "id": "manual-move-into-existing-folder-merges",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 285
+    },
+    {
+      "id": "manual-cross-library-move-into-existing-folder-merges",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 529
+    },
+    {
+      "id": "manual-delete-and-recreate-same-path",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 276
+    },
+    {
+      "id": "manual-delete-and-recreate-folder-with-new-file",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 264
+    },
+    {
+      "id": "manual-book-per-file-folder-move-multi-file",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 240
+    },
+    {
+      "id": "manual-cross-library-move-then-reseed-source",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 508
+    },
+    {
+      "id": "watcher-delete-primary-file-marks-missing",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 758
+    },
+    {
+      "id": "watcher-delete-folder",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 781
+    },
+    {
+      "id": "watcher-rename-file-in-place",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 776
+    },
+    {
+      "id": "watcher-rename-folder",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 789
+    },
+    {
+      "id": "watcher-move-root-file-into-subfolder",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 3913
+    },
+    {
+      "id": "watcher-move-subfolder-file-to-root",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 3881
+    },
+    {
+      "id": "watcher-cross-library-file-move",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 876
+    },
+    {
+      "id": "watcher-cross-library-folder-move",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 875
+    },
+    {
+      "id": "watcher-case-only-file-rename",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 774
+    },
+    {
+      "id": "watcher-non-content-file-creates-ignored",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 157
+    },
+    {
+      "id": "watcher-non-content-file-delete-ignored",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 148
+    },
+    {
+      "id": "watcher-book-per-file-delete-then-restore",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 1689
+    },
+    {
+      "id": "watcher-move-into-existing-folder-merges",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 3739
+    },
+    {
+      "id": "watcher-delete-and-recreate-same-path-within-debounce",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 130
+    },
+    {
+      "id": "watcher-delete-and-recreate-folder-with-new-file",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 1679
+    },
+    {
+      "id": "watcher-cross-library-move-then-reseed-source",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 4882
+    },
+    {
+      "id": "watcher-create-then-delete-new-path-within-debounce",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 168
+    },
+    {
+      "id": "watcher-book-per-file-cross-library-folder-move-multi-file",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 922
+    },
+    {
+      "id": "stateful-manual-delete-primary-preserves-data",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 287
+    },
+    {
+      "id": "stateful-manual-cross-library-move-preserves-book-identity",
+      "trigger": "manual",
+      "status": "passed",
+      "durationMs": 580
+    },
+    {
+      "id": "stateful-watcher-cross-library-move-preserves-book-identity",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 976
+    },
+    {
+      "id": "stateful-watcher-rename-folder-preserves-data",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 871
+    },
+    {
+      "id": "stateful-watcher-delete-then-restore-preserves-data",
+      "trigger": "watcher",
+      "status": "passed",
+      "durationMs": 1502
+    }
+  ]
+}
\ No newline at end of file