feat(adapters): FastAPI / Starlette durable background tasks

[h4syy]

Description

FastAPI's BackgroundTasks run inside the worker process and are lost if the worker restarts, redeploys, or is killed mid-task. This adds DurableBackgroundTasks, a drop-in dependency backed by LetItLoop's zero-daemon WAL: every task is journaled (fsync'd) before it runs, and any task interrupted by a crash is resumed automatically on the next startup — no Redis, no Celery, no separate worker.

Usage stays exactly as the issue describes:

from fastapi import FastAPI
from letitloop.adapters.fastapi import (
    DurableBackgroundTasks, durable_task, install_durable_background_tasks,
)

app = FastAPI()
install_durable_background_tasks(app)          # attaches WAL + resume-on-startup

@durable_task()                                # optional: stable key across renames
async def run_durable_report(report_id: str): ...

@app.post("/generate-report/{report_id}")
async def generate_report(report_id: str, background_tasks: DurableBackgroundTasks):
    background_tasks.add_task(run_durable_report, report_id)
    return {"status": "queued"}

How it works

• DurableTaskManager — the WAL ledger (tasks.wal.jsonl) plus the resume engine.
• DurableBackgroundTasks — exposed as Annotated[..., Depends(...)], so the bare bg: DurableBackgroundTasks annotation works with full type hints and native DI (rather than subclassing BackgroundTasks, which FastAPI would re-instantiate as the base type).
• durable_task(...) — optional decorator to pin a stable key; falls back to module:qualname so the snippet above works with no extra API.
• install_durable_background_tasks(app) — stores the manager on app.state and wraps the app lifespan to resume interrupted tasks on boot (any existing lifespan= is preserved).
• Two durability layers: at-least-once at the task level (PENDING → COMPLETED), and step-level skip via each task running inside a per-task @durable context.

FastAPI/Starlette are imported lazily, so import letitloop never requires them and the adapter keeps the suite's zero-mandatory-dependency guarantee.

Closes #93

Type of Change

• Bug fix
• New feature / capability
• New framework adapter (agent-durability-bench)
• Documentation update
• CI / Tooling improvement

Verification Checklist

• Unit tests added/updated and passing (pytest) — 14 new tests in tests/adapters/test_fastapi.py, including the crash-then-resume contract; DI tests skip cleanly when FastAPI is absent. Full -m fast suite (505 passed) with no regressions.
• AST invariants and types preserved — additive adapter only; no changes to the core kernel.
• Zero unapproved dependency additions — no new mandatory runtime deps; only an optional [fastapi] extra plus fastapi/httpx added to the dev extra so CI exercises the DI path.
• Self-reviewed for edge cases and clean error handling — non-serializable args fail fast; failed tasks are terminal (no retry storm); the resume sweep isolates per-task failures; stale per-task locks are auto-stolen on resume.

[sdageltc]

Fantastic contribution! The DurableBackgroundTasks dependency and install_durable_background_tasks(app) integration are clean, robust, and well-tested.

All 14 tests in tests/adapters/test_fastapi.py pass cleanly. Merging into main!