metacls 0.3.0__py3-none-any.whl

metacls/__init__.py

@@ -0,0 +1,8 @@
+"""MetaCLS — bulk metadata scrubbing for PDF, Office and image files.
+
+The remediation companion to MetaScout: MetaScout finds documents leaking
+metadata, MetaCLS strips it and produces a before/after proof report.
+"""
+from __future__ import annotations
+
+__version__ = "0.3.0"

metacls/_theme.py

@@ -0,0 +1,130 @@
+"""MetaCLS's own visual identity — one source of truth for the CSS used
+by both the local web UI (`web.py`) and the HTML report
+(`report/templates/`).
+
+Deliberately *not* MetaScout's look. MetaScout is blue-on-black, dark
+only. MetaCLS is emerald/slate with a "swept clean" motif and a proper
+light theme (follows `prefers-color-scheme`). Keeping the palette here,
+rather than copy-pasted into two files, is what keeps the two surfaces
+looking like one product.
+"""
+from __future__ import annotations
+
+# Design tokens. Dark is the primary look; the light block is a full
+# re-theme, not an afterthought.
+TOKENS_CSS = """
+:root {
+  --bg:        #0c1110;
+  --panel:     #141b1a;
+  --panel-2:   #1a2321;
+  --border:    #263230;
+  --text:      #e9efed;
+  --muted:     #93a5a0;
+  --accent:    #2dd4a7;   /* emerald-teal — MetaCLS's signature */
+  --accent-ink:#04140f;
+  --link:      #5ad1c4;
+  --good:      #2dd4a7;
+  --warn:      #f6c454;
+  --bad:       #f2778d;
+  --sweep: linear-gradient(100deg, rgba(45,212,167,.16), rgba(45,212,167,0) 60%);
+}
+@media (prefers-color-scheme: light) {
+  :root {
+    --bg:        #f4f7f6;
+    --panel:     #ffffff;
+    --panel-2:   #eef3f1;
+    --border:    #dde5e3;
+    --text:      #13201d;
+    --muted:     #5c6b67;
+    --accent:    #0f9e78;
+    --accent-ink:#ffffff;
+    --link:      #0c7c6a;
+    --good:      #0f9e78;
+    --warn:      #b57d12;
+    --bad:       #c2405a;
+    --sweep: linear-gradient(100deg, rgba(15,158,120,.10), rgba(15,158,120,0) 60%);
+  }
+}
+"""
+
+# Shared element + component styles. The `msc-` prefix keeps these from
+# colliding with anything in a report card's own escaped content.
+BASE_CSS = """
+* { box-sizing: border-box; }
+body { margin:0; background:var(--bg); color:var(--text);
+  font-family:"Inter",-apple-system,"Segoe UI",Roboto,sans-serif; font-size:14px;
+  line-height:1.5; -webkit-font-smoothing:antialiased; }
+a { color:var(--link); }
+code, .mono { font-family:ui-monospace,"SF Mono",SFMono-Regular,Menlo,monospace; }
+
+.msc-header { padding:26px 40px 20px; border-bottom:1px solid var(--border);
+  background:var(--sweep); background-repeat:no-repeat; }
+.msc-mark { font-weight:800; font-size:21px; letter-spacing:-.01em; }
+.msc-mark b { color:var(--accent); font-weight:800; }
+.msc-mark::before { content:""; display:inline-block; width:22px; height:3px; border-radius:2px;
+  background:var(--accent); margin:0 10px 5px 0; vertical-align:middle; }
+.msc-tag { color:var(--muted); font-size:12.5px; margin-top:5px; }
+.msc-nav { margin-top:12px; display:flex; gap:18px; }
+.msc-nav a { color:var(--muted); text-decoration:none; font-size:12.5px; font-weight:600;
+  padding-bottom:3px; border-bottom:2px solid transparent; }
+.msc-nav a.on, .msc-nav a:hover { color:var(--accent); border-bottom-color:var(--accent); }
+.msc-lang a { color:var(--muted); text-decoration:none; border:1px solid var(--border);
+  border-radius:999px; padding:3px 10px; font-size:11.5px; font-weight:700; margin-left:6px; }
+.msc-lang a.on { background:var(--accent); color:var(--accent-ink); border-color:var(--accent); }
+
+.msc-main { padding:26px 40px 72px; max-width:880px; margin:0 auto; }
+
+.msc-hero { border:1px solid var(--border); border-radius:14px; overflow:hidden;
+  background:var(--panel); margin-bottom:22px; }
+.msc-hero-band { padding:18px 22px; background:var(--sweep), var(--panel-2);
+  border-bottom:1px solid var(--border); display:flex; align-items:baseline; gap:12px; flex-wrap:wrap; }
+.msc-hero-state { font-size:19px; font-weight:800; letter-spacing:.02em; }
+.msc-hero-state.ok { color:var(--good); }
+.msc-hero-state.warn { color:var(--warn); }
+.msc-hero-state.bad { color:var(--bad); }
+.msc-hero-sub { color:var(--muted); font-size:12.5px; }
+.msc-stats { display:flex; flex-wrap:wrap; gap:10px; padding:16px 22px; }
+.msc-stat { flex:1; min-width:120px; background:var(--panel-2); border:1px solid var(--border);
+  border-radius:10px; padding:12px 14px; }
+.msc-stat .n { font-size:20px; font-weight:800; }
+.msc-stat .l { color:var(--muted); font-size:11.5px; margin-top:2px; letter-spacing:.02em; }
+.msc-stat.warn .n { color:var(--warn); }
+.msc-stat.bad .n { color:var(--bad); }
+
+.msc-card { background:var(--panel); border:1px solid var(--border); border-left:3px solid var(--border);
+  border-radius:12px; padding:18px 20px; margin-bottom:14px; }
+.msc-card.is-cleaned { border-left-color:var(--good); }
+.msc-card.is-skipped { border-left-color:var(--warn); }
+.msc-card.is-error   { border-left-color:var(--bad); }
+.msc-card.is-unsupported { border-left-color:var(--muted); }
+.msc-file { font-family:ui-monospace,"SF Mono",SFMono-Regular,Menlo,monospace; font-size:13px;
+  word-break:break-all; }
+.msc-meta { color:var(--muted); font-size:12px; }
+
+.msc-pill { display:inline-block; font-size:10.5px; font-weight:800; padding:2px 9px;
+  border-radius:999px; text-transform:uppercase; letter-spacing:.05em; }
+.msc-pill.cleaned{ background:color-mix(in srgb,var(--good) 18%,transparent); color:var(--good); }
+.msc-pill.skipped{ background:color-mix(in srgb,var(--warn) 18%,transparent); color:var(--warn); }
+.msc-pill.error{ background:color-mix(in srgb,var(--bad) 18%,transparent); color:var(--bad); }
+.msc-pill.unsupported{ background:color-mix(in srgb,var(--muted) 18%,transparent); color:var(--muted); }
+
+table.msc-diff { width:100%; border-collapse:collapse; margin-top:10px; font-size:12.5px; }
+table.msc-diff th, table.msc-diff td { text-align:left; padding:6px 10px;
+  border-bottom:1px solid var(--border); vertical-align:top; }
+table.msc-diff th { color:var(--muted); font-weight:600; }
+table.msc-diff td.was { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; color:var(--muted);
+  text-decoration:line-through; text-decoration-color:color-mix(in srgb,var(--bad) 60%,transparent);
+  word-break:break-word; }
+.msc-kept { color:var(--good); font-size:12px; margin-top:10px; }
+.msc-residual { color:var(--bad); font-size:12px; margin-top:10px; font-weight:600; }
+.msc-empty { color:var(--muted); font-size:12.5px; margin-top:8px; }
+
+.msc-btn { background:var(--accent); color:var(--accent-ink); border:0; border-radius:9px;
+  padding:12px 22px; font-weight:800; font-size:14px; cursor:pointer; }
+.msc-btn:disabled { opacity:.6; cursor:wait; }
+.msc-actions a { margin-right:16px; font-weight:600; font-size:13px; }
+"""
+
+
+def full_css() -> str:
+    return TOKENS_CSS + BASE_CSS

metacls/api/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .app import create_app
+
+__all__ = ["create_app"]

metacls/api/app.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import io
+import json
+import os
+import secrets
+import shutil
+import tempfile
+import time
+import zipfile
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+
+from fastapi import Depends, FastAPI, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import HTMLResponse, Response, StreamingResponse
+from werkzeug.utils import secure_filename
+
+from .. import __version__
+from ..cleaner import clean_file_list
+from ..config import CONTAINER_EXTENSIONS, MEDIA_EXTENSIONS, CleanConfig
+from ..engines import format_support
+from ..models import BatchReport
+from .jobs import Job, JobQueueFull, JobStore
+from .schemas import (
+    FormatsResponse,
+    HealthResponse,
+    JobCreated,
+    JobLogResponse,
+    JobStatusResponse,
+    JobSummary,
+)
+
+_CHUNK = 1024 * 1024
+
+
+def _rm(path: str) -> None:
+    try:
+        os.remove(path)
+    except OSError:
+        pass
+
+
+def _summary(job: Job) -> JobSummary | None:
+    return JobSummary(**job.summary) if job.summary else None
+
+
+def _links(request: Request, job_id: str) -> dict[str, str]:
+    return {
+        "self": str(request.url_for("get_job", job_id=job_id)),
+        "log": str(request.url_for("get_job_log", job_id=job_id)),
+        "report_json": str(request.url_for("get_job_report_json", job_id=job_id)),
+        "report_html": str(request.url_for("get_job_report_html", job_id=job_id)),
+        "download": str(request.url_for("get_job_download", job_id=job_id)),
+    }
+
+
+def _status(job: Job, request: Request) -> JobStatusResponse:
+    return JobStatusResponse(
+        job_id=job.job_id, status=job.status, run_id=job.run_id, file_count=job.file_count,
+        created_at=job.created_at.isoformat(),
+        started_at=job.started_at.isoformat() if job.started_at else None,
+        finished_at=job.finished_at.isoformat() if job.finished_at else None,
+        error=job.error,
+        summary=_summary(job),
+        links=_links(request, job.job_id),
+    )
+
+
+def _require(store: JobStore, job_id: str) -> Job:
+    job = store.get(job_id)
+    if job is None:
+        raise HTTPException(404, f"No job {job_id!r}. Jobs are in-memory and don't survive a restart.")
+    return job
+
+
+def _require_done(store: JobStore, job_id: str) -> Job:
+    job = _require(store, job_id)
+    if job.status != "done":
+        raise HTTPException(409, {"job_id": job.job_id, "status": job.status, "error": job.error,
+                                  "message": "Not ready — poll GET /v1/clean/{job_id} until status is 'done'."})
+    return job
+
+
+def create_app(*, output_dir: str = "./metacls_cleaned", max_workers: int = 2,
+               max_pending: int = 50, api_key: str | None = None,
+               max_upload_mb: int = 200, max_files: int = 50,
+               run_ttl_days: int = 0, log_json: bool = False) -> FastAPI:
+    """MetaCLS REST API — POST files, poll the job, pull the cleaned
+    files + report as a zip. Every job runs in a bounded background thread
+    pool so POST returns immediately; max_pending caps queued+running jobs.
+
+    `api_key`, when set, is required on every `/v1/*` route except the
+    open capability routes `/v1/health` and `/v1/formats` — as
+    `X-API-Key: <key>` or `Authorization: Bearer <key>`. `max_upload_mb` /
+    `max_files` bound a single request.
+    """
+    os.makedirs(output_dir, exist_ok=True)
+    store = JobStore(output_dir=output_dir, max_workers=max_workers, max_pending=max_pending,
+                     run_ttl_days=run_ttl_days)
+    max_upload_bytes = max_upload_mb * 1024 * 1024
+
+    def require_key(request: Request) -> None:
+        if not api_key:
+            return
+        supplied = request.headers.get("x-api-key")
+        if not supplied:
+            auth = request.headers.get("authorization", "")
+            if auth.lower().startswith("bearer "):
+                supplied = auth[7:]
+        if not (supplied and secrets.compare_digest(supplied, api_key)):
+            raise HTTPException(401, "missing or invalid API key")
+
+    guard = [Depends(require_key)]
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
+        yield
+        store.shutdown()
+
+    app = FastAPI(
+        title="MetaCLS API",
+        version=__version__,
+        description="Job-based bulk metadata scrubbing for PDF/Office/image files. "
+                    "Set an API key before exposing this — see the README.",
+        lifespan=lifespan,
+    )
+
+    if log_json:
+        @app.middleware("http")
+        async def _access_log(request: Request, call_next):
+            t0 = time.monotonic()
+            response = await call_next(request)
+            print(json.dumps({
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "method": request.method, "path": request.url.path,
+                "status": response.status_code,
+                "ms": round((time.monotonic() - t0) * 1000, 1),
+                "client": request.client.host if request.client else None,
+            }), flush=True)
+            return response
+
+    @app.get("/v1/health", response_model=HealthResponse, tags=["meta"])
+    def health() -> HealthResponse:
+        active = sum(1 for j in store.list() if j.status in ("queued", "running"))
+        return HealthResponse(status="ok", version=__version__, active_jobs=active)
+
+    @app.get("/v1/formats", response_model=FormatsResponse, tags=["meta"])
+    def formats() -> FormatsResponse:
+        """What this server can scrub: every supported extension, the
+        extensions each engine handles, and which optional pieces
+        (exiftool, LibreOffice, mutagen, py7zr, …) are installed here."""
+        return FormatsResponse(**format_support())
+
+    @app.post("/v1/clean", response_model=JobCreated, status_code=202, tags=["clean"],
+              dependencies=guard)
+    async def create_clean(
+        request: Request,
+        files: list[UploadFile] = File(..., description="Files to scrub."),
+        keep_title: bool = Form(False),
+        keep_color_profile: bool = Form(True),
+        recurse: bool = Form(False, description="Descend into .zip/.tar/.7z/.eml members."),
+        media: bool = Form(False, description="Also scrub uploaded audio/video files."),
+        in_place: bool = Form(False, description="Ignored — the API always returns cleaned copies."),
+        report_lang: str = Form("en"),
+    ) -> JobCreated:
+        uploads = [f for f in files if f.filename]
+        if not uploads:
+            raise HTTPException(422, "No files provided.")
+        if len(uploads) > max_files:
+            raise HTTPException(413, f"too many files ({len(uploads)} > {max_files})")
+
+        # Stream each upload straight to a temp file (never the whole batch
+        # in memory), enforcing the size cap as we go. The worker later
+        # moves them into the job's run dir.
+        staged: list[tuple[str, str]] = []  # (original name, temp path)
+        total = 0
+        try:
+            for f in uploads:
+                tmp = tempfile.NamedTemporaryFile(prefix="metacls-up-", delete=False)
+                try:
+                    while chunk := await f.read(_CHUNK):
+                        total += len(chunk)
+                        if total > max_upload_bytes:
+                            raise HTTPException(413, f"upload exceeds {max_upload_mb} MB")
+                        tmp.write(chunk)
+                finally:
+                    tmp.close()
+                staged.append((secure_filename(f.filename or "") or "file", tmp.name))
+        except Exception:
+            for _n, p in staged:
+                _rm(p)
+            raise
+
+        def work(log, run_path: str) -> BatchReport:
+            up_dir = os.path.join(run_path, "uploads")
+            os.makedirs(up_dir, exist_ok=True)
+            paths: list[str] = []
+            for name, tmp_path in staged:
+                dest = os.path.join(up_dir, name)
+                stem, ext = os.path.splitext(dest)
+                n = 1
+                while dest in paths or os.path.exists(dest):
+                    dest = f"{stem}({n}){ext}"
+                    n += 1
+                shutil.move(tmp_path, dest)
+                paths.append(dest)
+            filetypes = list(CleanConfig().filetypes)
+            if media:
+                filetypes = sorted(set(filetypes) | MEDIA_EXTENSIONS)
+            if recurse:
+                filetypes = sorted(set(filetypes) | CONTAINER_EXTENSIONS)
+            cfg = CleanConfig(
+                filetypes=filetypes,
+                output_dir=os.path.join(run_path, "cleaned"),
+                keep_fields=["Title"] if keep_title else [],
+                keep_color_profile=keep_color_profile,
+                recurse=recurse,
+            )
+            return clean_file_list(paths, cfg, base_dir=up_dir, log=log)
+
+        try:
+            job = store.submit(report_lang=report_lang if report_lang in ("en", "tr") else "en",
+                               file_count=len(staged), work=work)
+        except JobQueueFull as exc:
+            for _n, p in staged:
+                _rm(p)
+            raise HTTPException(429, str(exc)) from exc
+
+        return JobCreated(job_id=job.job_id, status="queued", run_id=job.run_id,
+                          created_at=job.created_at.isoformat(), links=_links(request, job.job_id))
+
+    @app.get("/v1/clean", response_model=list[JobStatusResponse], tags=["clean"], dependencies=guard)
+    def list_jobs(request: Request) -> list[JobStatusResponse]:
+        return [_status(j, request) for j in store.list()]
+
+    @app.get("/v1/clean/{job_id}", response_model=JobStatusResponse, tags=["clean"], name="get_job", dependencies=guard)
+    def get_job(job_id: str, request: Request) -> JobStatusResponse:
+        return _status(_require(store, job_id), request)
+
+    @app.get("/v1/clean/{job_id}/log", response_model=JobLogResponse, tags=["clean"], name="get_job_log", dependencies=guard)
+    def get_job_log(job_id: str) -> JobLogResponse:
+        job = _require(store, job_id)
+        return JobLogResponse(job_id=job.job_id, status=job.status, lines=list(job.log_lines))
+
+    @app.get("/v1/clean/{job_id}/report.json", tags=["clean"], name="get_job_report_json", dependencies=guard)
+    def get_job_report_json(job_id: str) -> Response:
+        job = _require_done(store, job_id)
+        with open(os.path.join(job.run_path, "report.json"), encoding="utf-8") as fh:
+            return Response(fh.read(), media_type="application/json")
+
+    @app.get("/v1/clean/{job_id}/report.html", response_class=HTMLResponse, tags=["clean"],
+             name="get_job_report_html", dependencies=guard)
+    def get_job_report_html(job_id: str) -> str:
+        job = _require_done(store, job_id)
+        with open(os.path.join(job.run_path, "report.html"), encoding="utf-8") as fh:
+            return fh.read()
+
+    @app.get("/v1/clean/{job_id}/download", tags=["clean"], name="get_job_download", dependencies=guard)
+    def get_job_download(job_id: str) -> StreamingResponse:
+        job = _require_done(store, job_id)
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+            cleaned = os.path.join(job.run_path, "cleaned")
+            for root, _, names in os.walk(cleaned):
+                for name in names:
+                    full = os.path.join(root, name)
+                    zf.write(full, os.path.join("cleaned", os.path.relpath(full, cleaned)))
+            for meta in ("report.json", "report.html"):
+                p = os.path.join(job.run_path, meta)
+                if os.path.isfile(p):
+                    zf.write(p, meta)
+        buf.seek(0)
+        headers = {"Content-Disposition": f'attachment; filename="metacls-{job.run_id}.zip"'}
+        return StreamingResponse(buf, media_type="application/zip", headers=headers)
+
+    return app

metacls/api/jobs.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sqlite3
+import threading
+import uuid
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timedelta, timezone
+
+from ..models import BatchReport
+from ..report import render_html_report, render_json_report
+
+# work(log, run_path) -> BatchReport. Takes run_path explicitly (assigned
+# before the job starts) so the worker never races on an attribute the
+# route handler sets only after submit() returns.
+JobWork = Callable[[Callable[[str], None], str], BatchReport]
+
+
+class JobQueueFull(RuntimeError):
+    """Raised by JobStore.submit() when max_pending jobs are already
+    queued or running — a bounded 429 instead of unbounded growth.
+    """
+
+
+class Job:
+    __slots__ = ("job_id", "run_id", "output_dir", "report_lang", "file_count", "status",
+                 "created_at", "started_at", "finished_at", "error", "log_lines", "summary")
+
+    def __init__(self, *, job_id: str, run_id: str, output_dir: str, report_lang: str,
+                 file_count: int = 0, status: str = "queued",
+                 created_at: datetime | None = None, started_at: datetime | None = None,
+                 finished_at: datetime | None = None, error: str | None = None,
+                 summary: dict | None = None) -> None:
+        self.job_id = job_id
+        self.run_id = run_id
+        self.output_dir = output_dir
+        self.report_lang = report_lang
+        self.file_count = file_count
+        self.status = status
+        self.created_at = created_at or datetime.now(timezone.utc)
+        self.started_at = started_at
+        self.finished_at = finished_at
+        self.error = error
+        self.summary = summary          # JobSummary dict, or None until done
+        self.log_lines: list[str] = []  # never persisted — process-local only
+
+    @property
+    def run_path(self) -> str:
+        return os.path.join(self.output_dir, self.run_id)
+
+
+class JobStore:
+    """Job registry backed by a bounded thread pool and a SQLite file
+    (`<output_dir>/jobs.db`) so job status survives a process restart.
+    Log lines stay in memory only; a job's report.json / report.html and
+    cleaned files are on disk under `<output_dir>/<run_id>/`.
+    """
+
+    _LOG_LIMIT = 1000
+
+    def __init__(self, *, output_dir: str, max_workers: int = 2, max_jobs_kept: int = 500,
+                 max_pending: int = 50, run_ttl_days: int = 0) -> None:
+        self.output_dir = output_dir
+        os.makedirs(output_dir, exist_ok=True)
+        self._executor = ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="metacls-job")
+        self._jobs: dict[str, Job] = {}
+        self._lock = threading.Lock()
+        self._max_jobs_kept = max_jobs_kept
+        self._max_pending = max_pending
+        self._run_ttl_days = run_ttl_days
+
+        self._db = sqlite3.connect(os.path.join(output_dir, "jobs.db"), check_same_thread=False)
+        self._db.execute("""
+            CREATE TABLE IF NOT EXISTS jobs (
+                job_id TEXT PRIMARY KEY, run_id TEXT, report_lang TEXT, file_count INTEGER,
+                status TEXT, created_at TEXT, started_at TEXT, finished_at TEXT,
+                error TEXT, summary_json TEXT
+            )""")
+        self._db.commit()
+        self._recover()
+        if run_ttl_days > 0:
+            self._sweep_expired()
+
+    # ------------------------------------------------------------------ persistence
+
+    def _recover(self) -> None:
+        rows = self._db.execute(
+            "SELECT job_id, run_id, report_lang, file_count, status, created_at, started_at, "
+            "finished_at, error, summary_json FROM jobs"
+        ).fetchall()
+        for (job_id, run_id, lang, fc, status, created, started, finished, error, summary_json) in rows:
+            if status in ("queued", "running"):
+                status, error = "error", (error or "interrupted by a service restart")
+                finished = finished or _now_iso()
+                self._db.execute("UPDATE jobs SET status=?, error=?, finished_at=? WHERE job_id=?",
+                                 (status, error, finished, job_id))
+            self._jobs[job_id] = Job(
+                job_id=job_id, run_id=run_id, output_dir=self.output_dir, report_lang=lang or "en",
+                file_count=fc or 0, status=status, created_at=_parse(created),
+                started_at=_parse(started), finished_at=_parse(finished), error=error,
+                summary=json.loads(summary_json) if summary_json else None,
+            )
+        self._db.commit()
+
+    def _persist(self, job: Job) -> None:
+        with self._lock:
+            self._db.execute(
+                "INSERT OR REPLACE INTO jobs VALUES (?,?,?,?,?,?,?,?,?,?)",
+                (job.job_id, job.run_id, job.report_lang, job.file_count, job.status,
+                 _iso(job.created_at), _iso(job.started_at), _iso(job.finished_at), job.error,
+                 json.dumps(job.summary) if job.summary else None),
+            )
+            self._db.commit()
+
+    def _sweep_expired(self) -> None:
+        cutoff = datetime.now(timezone.utc) - timedelta(days=self._run_ttl_days)
+        for job in list(self._jobs.values()):
+            if job.status in ("done", "error") and job.created_at < cutoff:
+                shutil.rmtree(job.run_path, ignore_errors=True)
+                with self._lock:
+                    self._jobs.pop(job.job_id, None)
+                    self._db.execute("DELETE FROM jobs WHERE job_id=?", (job.job_id,))
+                    self._db.commit()
+
+    # ------------------------------------------------------------------ api
+
+    def submit(self, *, report_lang: str, file_count: int, work: JobWork) -> Job:
+        with self._lock:
+            pending = sum(1 for j in self._jobs.values() if j.status in ("queued", "running"))
+            if pending >= self._max_pending:
+                raise JobQueueFull(
+                    f"{pending} job(s) already queued or running (limit {self._max_pending})."
+                )
+            job_id = uuid.uuid4().hex[:12]
+            run_id = f"api-{datetime.now().strftime('%Y%m%d-%H%M%S')}-{job_id[:8]}"
+            job = Job(job_id=job_id, run_id=run_id, output_dir=self.output_dir,
+                      report_lang=report_lang, file_count=file_count)
+            self._jobs[job_id] = job
+            self._evict_locked()
+        self._persist(job)
+        self._executor.submit(self._run, job, work)
+        return job
+
+    def get(self, job_id: str) -> Job | None:
+        with self._lock:
+            return self._jobs.get(job_id)
+
+    def list(self) -> list[Job]:
+        with self._lock:
+            return sorted(self._jobs.values(), key=lambda j: j.created_at, reverse=True)
+
+    def shutdown(self) -> None:
+        self._executor.shutdown(wait=False, cancel_futures=True)
+        try:
+            self._db.close()
+        except sqlite3.Error:
+            pass
+
+    # ------------------------------------------------------------------ internals
+
+    def _evict_locked(self) -> None:
+        if len(self._jobs) <= self._max_jobs_kept:
+            return
+        finished = sorted(
+            (j for j in self._jobs.values() if j.status in ("done", "error")),
+            key=lambda j: j.created_at,
+        )
+        for j in finished:
+            if len(self._jobs) <= self._max_jobs_kept:
+                break
+            self._jobs.pop(j.job_id, None)
+            self._db.execute("DELETE FROM jobs WHERE job_id=?", (j.job_id,))
+        self._db.commit()
+
+    def _push_log(self, job: Job, message: str) -> None:
+        with self._lock:
+            job.log_lines.append(message)
+            if len(job.log_lines) > self._LOG_LIMIT:
+                job.log_lines = job.log_lines[-self._LOG_LIMIT:]
+
+    def _run(self, job: Job, work: JobWork) -> None:
+        job.status = "running"
+        job.started_at = datetime.now(timezone.utc)
+        self._persist(job)
+        try:
+            report = work(lambda m: self._push_log(job, m), job.run_path)
+            os.makedirs(job.run_path, exist_ok=True)
+            with open(os.path.join(job.run_path, "report.json"), "w", encoding="utf-8") as fh:
+                fh.write(render_json_report(report))
+            with open(os.path.join(job.run_path, "report.html"), "w", encoding="utf-8") as fh:
+                fh.write(render_html_report(report, lang=job.report_lang))
+            job.summary = _summary_dict(report)
+            job.status = "done"
+        except Exception as exc:  # noqa: BLE001
+            job.error = str(exc)
+            job.status = "error"
+            self._push_log(job, f"! job failed: {exc}")
+        finally:
+            job.finished_at = datetime.now(timezone.utc)
+            self._persist(job)
+
+
+def _summary_dict(report: BatchReport) -> dict:
+    return {
+        "files": len(report.results),
+        "by_status": report.counts,
+        "fields_removed": report.fields_removed,
+        "files_with_residual": len(report.files_with_residual),
+        "files_errored": len(report.errored),
+    }
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _iso(dt: datetime | None) -> str | None:
+    return dt.isoformat() if dt else None
+
+
+def _parse(s: str | None) -> datetime | None:
+    if not s:
+        return None
+    try:
+        return datetime.fromisoformat(s)
+    except ValueError:
+        return None