celerp 2.3.2__tar.gz → 2.3.4__tar.gz

{celerp-2.3.2 → celerp-2.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celerp
-Version: 2.3.2
+Version: 2.3.4
 Summary: Free, self-hosted ERP for small businesses
 License: Business Source License 1.1
         

celerp-2.3.4/celerp/db.py

@@ -0,0 +1,136 @@
+# Copyright (c) 2026 Noah Severs
+# SPDX-License-Identifier: BUSL-1.1
+
+import os
+import re
+from contextlib import asynccontextmanager
+
+from sqlalchemy import text as _sql_text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from celerp.config import settings
+
+# Shared advisory-lock key that serialises schema migrations across every process
+# that might run them (the CLI upgrade command and the API startup phase). One
+# key, one source of truth, so two boots can never migrate the same database at
+# once.
+_MIGRATION_LOCK_KEY = 4207320001
+
+# Redacts the password in any Postgres URL: "://user:secret@host" -> "://user:***@host".
+# One authoritative masker for logs and surfaced errors so a connection string
+# never leaks a password.
+_DB_CREDENTIALS_RE = re.compile(r"(://[^:]+:)[^@]+(@)")
+
+
+def mask_db_credentials(text: str) -> str:
+    """Return text with any database URL password replaced by ``***``."""
+    return _DB_CREDENTIALS_RE.sub(r"\1***\2", text)
+
+# Request-connection timeouts (ms). One source of truth: the engine sets them in
+# server_settings, and lifecycle_timeouts_disabled restores exactly these values
+# after clearing them for startup work.
+_REQUEST_LOCK_TIMEOUT_MS = "3000"
+_REQUEST_STATEMENT_TIMEOUT_MS = "30000"
+
+# Pool budget: total_possible = (api_workers * (pool_size + max_overflow))
+#                              + (gui_workers * (gui_pool_size + gui_max_overflow))
+# Default workers 2 API + 1 GUI → 2*(10+5) + 1*(5+5) = 40 connections max.
+# Postgres default max_connections=100 leaves 60 for migrations, admin tools, etc.
+# If you increase worker counts, recalculate this budget before deploying.
+if os.environ.get("CELERP_TEST_NULLPOOL"):
+    # Test mode: a fresh connection per use that closes on return, so a failed
+    # test can't leave a poisoned/locked connection lingering in a pooled
+    # connection and block the next test's TRUNCATE. Only ever set by the test
+    # harness; no effect in production.
+    engine = create_async_engine(settings.database_url, future=True, poolclass=NullPool)
+else:
+    engine = create_async_engine(
+        settings.database_url,
+        future=True,
+        pool_pre_ping=True,
+        pool_size=10,
+        max_overflow=5,
+        # Bound how long any query may wait on a lock or run, so a stuck query is
+        # cancelled instead of pinning one of the few pooled connections for the
+        # full request lifetime (lock_timeout 3s, statement_timeout 30s, in ms).
+        # This is a per-connection default, so it applies to every request AND
+        # every pooled background job (connector syncs, the gateway, the daily
+        # scheduler) - all of which must stay bounded. Startup reconciliation and
+        # the projection rebuild are the only work that legitimately runs longer;
+        # they use lifecycle_engine below instead of this pool, and the migration
+        # advisory-lock wait self-exempts via lifecycle_timeouts_disabled.
+        connect_args={
+            "server_settings": {
+                "lock_timeout": _REQUEST_LOCK_TIMEOUT_MS,
+                "statement_timeout": _REQUEST_STATEMENT_TIMEOUT_MS,
+            }
+        },
+    )
+SessionLocal = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+# Lifecycle/maintenance engine: a separate NullPool engine carrying NO statement
+# or lock timeout. Startup reconciliation (create_all, module on_modules_ready
+# seed hooks, the develop->release projection rebuild, the one-time status-doc and
+# COGS backfills) and the on-demand projection rebuild routes run whole-table
+# DELETEs and full-ledger replays that can legitimately exceed the request
+# statement_timeout on a mature database. Running them on the bounded request pool
+# would cancel them at 30s - permanently blocking boot's upgrade guard and the
+# /ledger/rebuild recovery route. They run on this engine instead. NullPool: these
+# operations are rare and brief, so no pooled slot is reserved and the request pool
+# budget above is unaffected (at most one transient connection per concurrent
+# lifecycle op).
+lifecycle_engine = create_async_engine(settings.database_url, future=True, poolclass=NullPool)
+LifecycleSessionLocal = async_sessionmaker(
+    lifecycle_engine, class_=AsyncSession, expire_on_commit=False
+)
+
+
+@asynccontextmanager
+async def lifecycle_timeouts_disabled(conn):
+    """Clear the request statement/lock timeouts on the migration lock connection.
+
+    The migration advisory-lock wait runs on a connection drawn from the bounded
+    request engine (so a single engine serialises boots), but a second worker's
+    wait can legitimately exceed the 30s statement_timeout while the first worker
+    migrates, and a cancelled wait aborts the boot. This sets both timeouts to 0
+    (unbounded) for the block and restores the request defaults on exit, so the
+    connection returned to the pool still carries them. Other long-running startup
+    work uses lifecycle_engine (no timeout) rather than this in-place exemption.
+    Postgres only; a no-op on other dialects, which have no such settings.
+    """
+    if conn.dialect.name != "postgresql":
+        yield
+        return
+    await conn.execute(_sql_text("SET statement_timeout = 0"))
+    await conn.execute(_sql_text("SET lock_timeout = 0"))
+    try:
+        yield
+    finally:
+        await conn.execute(_sql_text(f"SET statement_timeout = {_REQUEST_STATEMENT_TIMEOUT_MS}"))
+        await conn.execute(_sql_text(f"SET lock_timeout = {_REQUEST_LOCK_TIMEOUT_MS}"))
+
+
+async def get_session() -> AsyncSession:
+    async with SessionLocal() as session:
+        yield session
+
+
+@asynccontextmanager
+async def get_session_ctx():
+    """Standalone async context manager for use outside FastAPI request handlers."""
+    async with SessionLocal() as session:
+        yield session
+
+
+@asynccontextmanager
+async def get_lifecycle_session_ctx():
+    """Session on the unbounded lifecycle_engine, for known long-running work.
+
+    Use for the projection rebuild and startup backfills: a full rebuild's
+    whole-table DELETE and full-ledger replay can exceed the request
+    statement_timeout on a mature database, and must not be cancelled. Ordinary
+    request and background work uses get_session/get_session_ctx (bounded).
+    """
+    async with LifecycleSessionLocal() as session:
+        yield session

{celerp-2.3.2 → celerp-2.3.4}/celerp/events/schemas.py

@@ -546,6 +546,15 @@ class DocUnvoided(BaseModel):
     restored_status: str
 
 
+class DocClosed(BaseModel):
+    reason: str | None = None
+    pre_close_status: str | None = None
+
+
+class DocReopened(BaseModel):
+    restored_status: str
+
+
 class DocSent(BaseModel):
     sent_via: str | None = None
     sent_to: str | None = None
@@ -1162,6 +1171,8 @@ EVENT_SCHEMA_MAP: dict[str, type[BaseModel]] = {
     "doc.voided": DocVoided,
     "doc.reverted_to_draft": DocRevertedToDraft,
     "doc.unvoided": DocUnvoided,
+    "doc.closed": DocClosed,
+    "doc.reopened": DocReopened,
     "doc.converted_to_bill": DocConvertedToBill,
     "doc.sent": DocSent,
     "doc.payment.received": DocPaymentReceived,

{celerp-2.3.2 → celerp-2.3.4}/celerp/gateway/client.py

@@ -26,7 +26,6 @@ from websockets.exceptions import ConnectionClosed
 
 log = logging.getLogger(__name__)
 
-_PING_INTERVAL = 30   # seconds
 _BACKOFF_MAX = 60     # seconds
 # Consecutive auth rejections before the client stops retrying: a rejected
 # credential never heals on its own, so beyond a small allowance for a
@@ -37,6 +36,10 @@ _AUTH_FAILED_MAX = 3
 # a revoke-then-reshare so it does not flap connect/disconnect).
 _REAP_INTERVAL = 15 * 60   # seconds
 _REAP_GRACE = 5 * 60       # seconds
+# A single websocket send that cannot be handed to the transport within this long means the
+# socket is wedged (a stalled or backpressured peer). Bound every send so it surfaces as an
+# error instead of pinning the proxy task holding a relay slot forever.
+_SEND_DEADLINE = 30        # seconds
 
 
 def _shop_key(handle: str | None) -> str:
@@ -85,6 +88,22 @@ class GatewayClient:
         # Hold strong refs to fire-and-forget tasks so the loop can't GC them mid-run
         # (a dropped task = a lost proxy response or webhook sync).
         self._bg_tasks: set = set()
+        # In-flight proxy tasks keyed by relay request id so an http.cancel frame can
+        # abort exactly the one request it names, and no other.
+        self._inflight: dict[str, asyncio.Task] = {}
+        # Connection generation: bumped on every teardown so a response produced by a
+        # request that outlived its socket can be recognised as stale and dropped
+        # rather than sent on the freshly rebuilt connection.
+        self._generation: int = 0
+        # One shared httpx client for all proxied requests, built lazily with bounded
+        # connection limits. A fresh client per request opened an unbounded number of
+        # pools under load; one bounded client caps the concurrency into the local app.
+        self._http_client: Any = None
+        # Observability counters for the proxy path, surfaced when the connection ends.
+        self._proxied_count = 0
+        self._cancelled_count = 0
+        self._timeout_count = 0
+        self._stale_dropped_count = 0
         # Resolve local server ports for proxy routing.
         # In Electron builds the ports are dynamic; Electron passes them via
         # CELERP_API_PORT / CELERP_UI_PORT env vars so we don't rely on the
@@ -122,6 +141,22 @@ class GatewayClient:
         self._bg_tasks.add(task)
         task.add_done_callback(self._bg_tasks.discard)
 
+    def _spawn_proxy(self, payload: dict) -> None:
+        """Run a proxied request fire-and-forget, keyed by its relay request id so an
+        http.cancel frame can abort exactly that task. The key is cleared when the task
+        finishes (a cancel arriving after completion is then a harmless no-op)."""
+        request_id = payload.get("id", "")
+        task = asyncio.create_task(self._handle_proxy_request(payload))
+        self._bg_tasks.add(task)
+        self._inflight[request_id] = task
+
+        def _done(t: asyncio.Task) -> None:
+            self._bg_tasks.discard(t)
+            if self._inflight.get(request_id) is t:
+                del self._inflight[request_id]
+
+        task.add_done_callback(_done)
+
     # ── Public API ─────────────────────────────────────────────────────
 
     async def run(self) -> None:
@@ -198,6 +233,7 @@ class GatewayClient:
                 await ws.close()
             except Exception:
                 pass
+        await self._close_http_client()
 
     async def _should_reap(self) -> bool:
         """A free instance with no live share and no recent proxied request should
@@ -293,40 +329,61 @@ class GatewayClient:
             import ssl as _ssl
             _ssl_ctx = _ssl.create_default_context()
             _ssl_ctx.set_alpn_protocols(["http/1.1"])
-        async with websockets.connect(
-            self._url, ssl=_ssl_ctx, ping_interval=20, ping_timeout=20, max_size=160 * 1024 * 1024
-        ) as ws:
-            self._ws = ws
-            # Read current TOS version from config
-            from celerp.config import read_config
-            cfg = read_config() or {}
-            tos_version = cfg.get("cloud", {}).get("tos_version", "")
-            # App version: the Electron wrapper passes the release version via
-            # CELERP_APP_VERSION; fall back to the package version. Sent on every
-            # connect so the handshake reflects the build that is actually running.
-            from celerp import __version__ as _pkg_version
-            app_version = os.environ.get("CELERP_APP_VERSION") or _pkg_version
-            # Send hello handshake
-            await self._send(ws, {
-                "type": "hello",
-                "id": str(uuid.uuid4()),
-                "payload": {
-                    "gateway_token": self._token,
-                    "instance_id": self._instance_id,
-                    "tos_version": tos_version,
-                    "version": app_version,
-                },
-            })
-            # Message dispatch loop
-            async for raw in ws:
-                try:
-                    msg = json.loads(raw)
-                except json.JSONDecodeError:
-                    log.warning("Gateway sent non-JSON frame: %r", raw)
-                    continue
-                await self._dispatch(msg)
-        self._ws = None
-        self._set_status("inactive")
+        try:
+            async with websockets.connect(
+                self._url, ssl=_ssl_ctx, ping_interval=20, ping_timeout=20, max_size=160 * 1024 * 1024
+            ) as ws:
+                self._ws = ws
+                # Read current TOS version from config
+                from celerp.config import read_config
+                cfg = read_config() or {}
+                tos_version = cfg.get("cloud", {}).get("tos_version", "")
+                # App version: the Electron wrapper passes the release version via
+                # CELERP_APP_VERSION; fall back to the package version. Sent on every
+                # connect so the handshake reflects the build that is actually running.
+                from celerp import __version__ as _pkg_version
+                app_version = os.environ.get("CELERP_APP_VERSION") or _pkg_version
+                # Send hello handshake
+                await self._send(ws, {
+                    "type": "hello",
+                    "id": str(uuid.uuid4()),
+                    "payload": {
+                        "gateway_token": self._token,
+                        "instance_id": self._instance_id,
+                        "tos_version": tos_version,
+                        "version": app_version,
+                    },
+                })
+                # Message dispatch loop
+                async for raw in ws:
+                    try:
+                        msg = json.loads(raw)
+                    except json.JSONDecodeError:
+                        log.warning("Gateway sent non-JSON frame: %r", raw)
+                        continue
+                    await self._dispatch(msg)
+        finally:
+            # Teardown runs on every exit - clean end of the message stream OR an
+            # abnormal disconnect raised mid-serve. Kept in a finally so an exception
+            # from the async-for can't leave a dangling socket, an unfenced generation,
+            # and a stuck status behind.
+            self._ws = None
+            # A new generation for the next connection: any proxy response still in
+            # flight from this socket is now stale and must not be sent on the rebuilt
+            # one. Cancel the in-flight proxy tasks that belong to the dead connection -
+            # their responses can never be delivered on a socket that no longer exists.
+            self._generation += 1
+            for task in list(self._inflight.values()):
+                if not task.done():
+                    task.cancel()
+            self._inflight.clear()
+            log.debug(
+                "Gateway proxy activity this connection: proxied=%d cancelled=%d "
+                "timed_out=%d stale_dropped=%d",
+                self._proxied_count, self._cancelled_count,
+                self._timeout_count, self._stale_dropped_count,
+            )
+            self._set_status("inactive")
 
     async def _dispatch(self, msg: dict) -> None:
         msg_type = msg.get("type", "")
@@ -414,7 +471,13 @@ class GatewayClient:
             set_subscription_state(tier, status)
 
         elif msg_type == "http.request":
-            self._spawn(self._handle_proxy_request(payload))
+            self._spawn_proxy(payload)
+
+        elif msg_type == "http.cancel":
+            request_id = payload.get("id", "")
+            task = self._inflight.get(request_id)
+            if task is not None and not task.done():
+                task.cancel()
 
         elif msg_type == "shopify.webhook":
             self._spawn(self._handle_shopify_webhook(payload))
@@ -533,6 +596,31 @@ class GatewayClient:
         except Exception as exc:
             log.warning("invoice.payment handling failed (entity=%s): %s", entity_id, exc)
 
+    def _get_http_client(self):
+        """Return the one shared httpx client used for every proxied request, building
+        it lazily on first use. A bounded connection pool caps how many concurrent
+        requests this client can drive into the local app, so a burst of relayed
+        requests can no longer open an unbounded number of pools. The default timeout
+        is the fixed cap; a per-request timeout_ms tightens it further."""
+        import httpx
+
+        if self._http_client is None:
+            self._http_client = httpx.AsyncClient(
+                timeout=180.0,
+                limits=httpx.Limits(max_connections=32, max_keepalive_connections=8),
+            )
+        return self._http_client
+
+    async def _close_http_client(self) -> None:
+        """Close the shared httpx client if one was built. Safe to call when none was."""
+        client = self._http_client
+        self._http_client = None
+        if client is not None:
+            try:
+                await client.aclose()
+            except Exception:
+                pass
+
     async def _handle_proxy_request(self, payload: dict) -> None:
         """Handle a proxied HTTP request from the relay.
 
@@ -545,10 +633,14 @@ class GatewayClient:
         local access.
         """
         import base64
-        import httpx
 
         # Activity stamp for the reaper's grace window: any proxied request counts.
         self._last_request_monotonic = time.monotonic()
+        self._proxied_count += 1
+        # The generation this request belongs to: if the socket is rebuilt before the
+        # response is ready, self._generation advances past this and the response is
+        # dropped rather than sent on a connection that never issued the request.
+        generation = self._generation
 
         request_id = payload.get("id", "")
         method = payload.get("method", "GET")
@@ -557,6 +649,13 @@ class GatewayClient:
         headers = payload.get("headers", {})
         body_b64 = payload.get("body_b64", "")
         body = base64.b64decode(body_b64) if body_b64 else None
+        # Additive per-request deadline: a numeric timeout_ms bounds this request below
+        # the fixed cap so a single slow local handler can't pin a relay slot for 180s.
+        # Absent or non-numeric leaves the default cap in force.
+        timeout_ms = payload.get("timeout_ms")
+        deadline_s: float | None = None
+        if isinstance(timeout_ms, (int, float)) and not isinstance(timeout_ms, bool) and timeout_ms > 0:
+            deadline_s = timeout_ms / 1000.0
 
         # SSE / long-poll paths cannot be proxied over the WS request/response
         # protocol. Return an empty stream so the browser doesn't 500.
@@ -599,47 +698,98 @@ class GatewayClient:
         if query:
             url = f"{url}?{query}"
 
+        client = self._get_http_client()
         try:
-            async with httpx.AsyncClient(timeout=180.0) as client:
+            if deadline_s is not None:
+                # asyncio.wait_for, not asyncio.timeout: the latter is 3.11+, and this package
+                # supports Python >=3.10 where it does not exist. wait_for cancels the request and
+                # raises TimeoutError on the deadline, which the handler below turns into an error
+                # response.
+                resp = await asyncio.wait_for(
+                    client.request(
+                        method=method,
+                        url=url,
+                        headers=headers,
+                        content=body,
+                    ),
+                    deadline_s,
+                )
+            else:
                 resp = await client.request(
                     method=method,
                     url=url,
                     headers=headers,
                     content=body,
                 )
-            resp_body_b64 = base64.b64encode(resp.content).decode() if resp.content else ""
-            # Serialize as an ORDERED LIST of pairs (not a dict): a response can carry several
-            # Set-Cookie headers (login/refresh emit access_token + refresh_token), and a dict would
-            # collapse them into one comma-joined value the browser can't parse — so the refresh
-            # cookie never reaches the browser and the session dies at the access token's hard cap.
-            # multi_items() keeps each header separate. Drop content-length; the relay recomputes it.
-            _skip = {"transfer-encoding", "connection", "keep-alive", "content-length"}
-            resp_headers = [
-                [k, v] for k, v in resp.headers.multi_items()
-                if k.lower() not in _skip
-            ]
-            await self._send(self._ws, {
-                "type": "http.response",
-                "payload": {
-                    "id": request_id,
-                    "status": resp.status_code,
-                    "headers": resp_headers,
-                    "body_b64": resp_body_b64,
-                },
-            })
+        except asyncio.CancelledError:
+            # http.cancel aborted this request: emit nothing and let the cancellation
+            # propagate so the task is recorded cancelled.
+            self._cancelled_count += 1
+            raise
+        except TimeoutError:
+            # The per-request deadline elapsed before the local handler answered. Surface
+            # it as an error response instead of hanging to the fixed cap.
+            self._timeout_count += 1
+            log.warning("Proxy request timed out after %sms for %s %s", timeout_ms, method, path)
+            if generation == self._generation:
+                await self._send(self._ws, {
+                    "type": "http.response",
+                    "payload": {
+                        "id": request_id,
+                        "status": 504,
+                        "headers": [["content-type", "text/plain"]],
+                        "body_b64": base64.b64encode(b"Local app timed out").decode(),
+                    },
+                })
+            else:
+                self._stale_dropped_count += 1
+            return
         except Exception as exc:
             log.warning("Proxy request failed for %s %s: %s", method, path, exc)
-            await self._send(self._ws, {
-                "type": "http.response",
-                "payload": {
-                    "id": request_id,
-                    "status": 502,
-                    "headers": [["content-type", "text/plain"]],
-                    "body_b64": base64.b64encode(
-                        f"Local app error: {type(exc).__name__}: {exc}".encode()
-                    ).decode(),
-                },
-            })
+            if generation == self._generation:
+                await self._send(self._ws, {
+                    "type": "http.response",
+                    "payload": {
+                        "id": request_id,
+                        "status": 502,
+                        "headers": [["content-type", "text/plain"]],
+                        "body_b64": base64.b64encode(
+                            f"Local app error: {type(exc).__name__}: {exc}".encode()
+                        ).decode(),
+                    },
+                })
+            else:
+                self._stale_dropped_count += 1
+            return
+
+        # The socket that carried this request may have been rebuilt while it was in
+        # flight. A response from a superseded generation belongs to a connection the
+        # relay no longer has; sending it on the new socket would answer the wrong
+        # request, so it is dropped.
+        if generation != self._generation:
+            self._stale_dropped_count += 1
+            return
+
+        resp_body_b64 = base64.b64encode(resp.content).decode() if resp.content else ""
+        # Serialize as an ORDERED LIST of pairs (not a dict): a response can carry several
+        # Set-Cookie headers (login/refresh emit access_token + refresh_token), and a dict would
+        # collapse them into one comma-joined value the browser can't parse, so the refresh
+        # cookie never reaches the browser and the session dies at the access token's hard cap.
+        # multi_items() keeps each header separate. Drop content-length; the relay recomputes it.
+        _skip = {"transfer-encoding", "connection", "keep-alive", "content-length"}
+        resp_headers = [
+            [k, v] for k, v in resp.headers.multi_items()
+            if k.lower() not in _skip
+        ]
+        await self._send(self._ws, {
+            "type": "http.response",
+            "payload": {
+                "id": request_id,
+                "status": resp.status_code,
+                "headers": resp_headers,
+                "body_b64": resp_body_b64,
+            },
+        })
 
     async def send_message(self, msg_type: str, **payload) -> None:
         """Send a JSON message over the active WS connection.
@@ -652,7 +802,12 @@ class GatewayClient:
 
     @staticmethod
     async def _send(ws, message: dict) -> None:
-        await ws.send(json.dumps(message))
+        # Bound the send: a websocket send awaits until the frame is handed to the transport, and a
+        # stalled or backpressured peer would otherwise block it forever, pinning the proxy task and
+        # its relay slot. On the deadline the send is cancelled and TimeoutError surfaces to the
+        # caller, which lets the wedged socket be torn down and rebuilt. asyncio.wait_for, not
+        # asyncio.timeout: the latter is 3.11+ and this package supports Python >=3.10.
+        await asyncio.wait_for(ws.send(json.dumps(message)), _SEND_DEADLINE)
 
 
 # Module-level singleton — set by main.py lifespan

{celerp-2.3.2 → celerp-2.3.4}/celerp/main.py

@@ -12,7 +12,7 @@ from slowapi import Limiter, _rate_limit_exceeded_handler
 from slowapi.errors import RateLimitExceeded
 from slowapi.util import get_remote_address
 
-from celerp.db import engine, mask_db_credentials
+from celerp.db import engine, lifecycle_engine, mask_db_credentials
 from celerp.inventory_codes import BarcodeConflictError
 from celerp.config import settings, assert_secure_jwt, ensure_instance_id, load_cloud_config, load_backup_config
 load_cloud_config()
@@ -164,7 +164,7 @@ async def _try_auto_activate() -> None:
 async def lifespan(_app: FastAPI):
     (settings.data_dir / "static" / "attachments").mkdir(parents=True, exist_ok=True)
     try:
-        async with engine.begin() as conn:
+        async with lifecycle_engine.begin() as conn:
             await conn.run_sync(Base.metadata.create_all)
     except Exception as exc:
         masked_url = mask_db_credentials(settings.database_url)
@@ -205,19 +205,20 @@ async def lifespan(_app: FastAPI):
             register_api_routes(_app, _loaded_modules)
             # Module models register on Base.metadata at import time.
             # Run create_all again so module tables are created (idempotent).
-            async with engine.begin() as conn:
+            async with lifecycle_engine.begin() as conn:
                 await conn.run_sync(Base.metadata.create_all)
             # Allow modules to backfill data for existing companies (e.g. seed
             # chart of accounts when accounting module is first enabled on an
             # instance that already has companies).
             from celerp.modules.slots import fire_lifecycle as _fire
-            from celerp.db import SessionLocal as _SessionLocal
+            from celerp.db import LifecycleSessionLocal as _LifecycleSession
             # Best-effort, like the two sibling blocks below: a hook that fails
             # during flush poisons the shared session, so the commit raises.
             # Roll back and log at ERROR rather than let that crash boot - the
             # manufacturing seed hook, for one, must never be able to take the
-            # app down.
-            async with _SessionLocal() as _sess:
+            # app down. Seed hooks can replay large ledgers, so they run on the
+            # unbounded lifecycle engine, not the timeout-bounded request pool.
+            async with _LifecycleSession() as _sess:
                 try:
                     await _fire("on_modules_ready", session=_sess)
                     await _sess.commit()
@@ -236,7 +237,7 @@ async def lifespan(_app: FastAPI):
                 _demoted = demoted_first_party(_enabled)
                 if _demoted:
                     from celerp.modules.demotion import notify_demoted_modules
-                    async with _SessionLocal() as _dsess:
+                    async with _LifecycleSession() as _dsess:
                         await notify_demoted_modules(_dsess, _demoted)
                         await _dsess.commit()
             except Exception:
@@ -256,7 +257,7 @@ async def lifespan(_app: FastAPI):
     # marker so it runs once per version. Non-fatal: a failure must not block
     # boot — the marker stays unset and a later boot retries.
     try:
-        from celerp.db import SessionLocal as _GuardSession
+        from celerp.db import LifecycleSessionLocal as _GuardSession
         from celerp.services.dev_release_guard import run_upgrade_guard
         async with _GuardSession() as _guard_sess:
             await run_upgrade_guard(_guard_sess)
@@ -271,7 +272,7 @@ async def lifespan(_app: FastAPI):
     # or consigned in before that field shipped, so their inventory status links
     # to its document. Marker-gated (runs once); non-fatal like the guard above.
     try:
-        from celerp.db import SessionLocal as _BackfillSession
+        from celerp.db import LifecycleSessionLocal as _BackfillSession
         from celerp.services.status_doc_backfill import run_status_doc_backfill
         async with _BackfillSession() as _bf_sess:
             await run_status_doc_backfill(_bf_sess)
@@ -287,7 +288,7 @@ async def lifespan(_app: FastAPI):
     # (runs once; retries stragglers while any doc is locked or errored);
     # non-fatal like the backfill above.
     try:
-        from celerp.db import SessionLocal as _CogsSession
+        from celerp.db import LifecycleSessionLocal as _CogsSession
         from celerp.services.cogs_backfill import run_cogs_backfill
         async with _CogsSession() as _cogs_sess:
             await run_cogs_backfill(_cogs_sess)