rootsign 0.2.0__tar.gz → 0.2.1__tar.gz

rootsign-0.2.1/.github/dependabot.yml

@@ -0,0 +1,31 @@
+# Dependabot keeps the SHA-pinned GitHub Actions fresh.
+#
+# Why this file exists: `.github/workflows/release.yml` pins
+# pypa/gh-action-pypi-publish to an immutable commit SHA rather than the
+# mutable `release/v1` branch (CodeQL actions/unpinned-tag). That closes the
+# supply-chain hole on the step that mints our PyPI Trusted Publishing OIDC
+# token — but a hand-pinned SHA rots silently, which is its own risk. Dependabot
+# bumps the pin and rewrites the trailing `# vX.Y.Z` comment for us, so the pin
+# stays both immutable and current.
+#
+# Scope note: only `github-actions` is enabled. The Python dependency surface is
+# deliberately left to security alerts rather than routine version-update PRs —
+# the framework-contract CI jobs pin langgraph/crewai to specific minor ranges
+# on purpose, and version-bump PRs against those would be noise.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      # Matches the repo convention: type(scope): short description
+      prefix: "chore(ci)"
+    labels:
+      - dependencies
+    groups:
+      # One PR per week for routine action bumps instead of one per action.
+      # Security-relevant bumps still arrive on their own via alerts.
+      github-actions:
+        patterns:
+          - "*"

{rootsign-0.2.0 → rootsign-0.2.1}/.github/workflows/ci.yml

@@ -6,6 +6,13 @@ on:
   pull_request:
     branches: [main]
 
+# Least privilege for every job below. CI only ever reads the repo — no job
+# publishes, comments, or writes checks — so the read-only default holds for
+# all of them and no job needs an override. Without this block the workflow
+# inherits the repo-wide default token scopes (CodeQL actions/missing-workflow-permissions).
+permissions:
+  contents: read
+
 jobs:
   unit-tests:
     name: Unit tests (Python ${{ matrix.python-version }})
@@ -38,8 +45,8 @@ jobs:
       TEST_DATABASE_URL: postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_test
       TEST_DATABASE_URL_SYNC: postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_test
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install
@@ -81,8 +88,8 @@ jobs:
       TEST_DATABASE_URL: postgresql+asyncpg://rootsign:rootsign@localhost:5432/rootsign_test
       TEST_DATABASE_URL_SYNC: postgresql+psycopg2://rootsign:rootsign@localhost:5432/rootsign_test
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       # mcp extra so the DB-backed MCP proxy integration test
@@ -118,8 +125,8 @@ jobs:
     env:
       ROOTSIGN_SKIP_DB_BOOTSTRAP: '1'
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Install with langgraph extra
@@ -146,8 +153,8 @@ jobs:
     env:
       ROOTSIGN_SKIP_DB_BOOTSTRAP: '1'
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Install with crewai extra
@@ -170,8 +177,8 @@ jobs:
     env:
       ROOTSIGN_SKIP_DB_BOOTSTRAP: '1'
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Install with mcp extra
@@ -188,8 +195,8 @@ jobs:
     name: No-extras install (DB-free core)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Install core only (no extras)
@@ -231,6 +238,65 @@ jobs:
               assert "rootsign[postgres]" in str(e), e
               print("RootSignPostgresExtraRequired raised OK")
           PY
+      - name: Console scripts run DB-free (CLI tripwire)
+        # `import rootsign` passing is NOT sufficient. The console script entry
+        # point imports `rootsign.sdk.cli`, a different import graph that the
+        # checks above never touch — a module-level `from rootsign.database
+        # import AsyncSessionLocal` there crashed EVERY `rootsign ...`
+        # invocation on a bare install (even `version` and `verify --local`,
+        # neither of which needs a DB) while this job stayed green. This step
+        # exercises the script itself so that class of regression fails here.
+        run: |
+          set -euo pipefail
+          rootsign version
+          rootsign --help > /dev/null
+          # The operator CLI is a separate entry point (rootsign.cli:app) with
+          # its own import graph. --help and the docker-only subcommands must
+          # work without the postgres extra.
+          rootsign-admin --help > /dev/null
+          rootsign-admin start-db --help > /dev/null
+          rootsign-admin stop-db --help > /dev/null
+          # Store-exported fixture, not a checked-in file: let the JSONL backend
+          # write a real session so the chain is produced by the same code path
+          # that verifies it. Never hand-construct a self_hash (ADR-001).
+          SESSION_ID="$(python - <<'PY'
+          import asyncio, rootsign
+
+          rootsign.init(agent="ci-tripwire")
+
+          @rootsign.trace()
+          async def add(a: int, b: int) -> int:
+              return a + b
+
+          async def main():
+              async with rootsign.session() as ctx:
+                  await add(2, 3)
+                  return ctx.session_id
+
+          print(asyncio.run(main()))
+          PY
+          )"
+          rootsign verify --local "$HOME/.rootsign/sessions/$SESSION_ID.jsonl"
+          echo "console scripts OK, DB-free"
+      - name: DB-backed subcommands fail with the install hint, not a traceback
+        # The other half of the same bug: these commands legitimately need the
+        # extra, but must say so in one line and exit 1 rather than dumping a
+        # ModuleNotFoundError traceback at the user.
+        run: |
+          set -uo pipefail
+          # Every DB-backed subcommand across BOTH console scripts.
+          for cmd in "rootsign verify 550e8400-e29b-41d4-a716-446655440001" \
+                     "rootsign approve --list" \
+                     "rootsign approve 550e8400-e29b-41d4-a716-446655440001" \
+                     "rootsign-admin status" \
+                     "rootsign-admin init"; do
+            out="$($cmd 2>&1)" && { echo "expected failure: $cmd"; exit 1; }
+            echo "$out" | grep -q "rootsign\[postgres\]" || {
+              echo "missing install hint for: $cmd"; echo "$out"; exit 1; }
+            echo "$out" | grep -qi "Traceback" && {
+              echo "leaked traceback for: $cmd"; echo "$out"; exit 1; }
+            echo "$cmd -> actionable error OK"
+          done
       # NOTE: we deliberately do NOT run `pytest tests/contract/no_extras/`
       # here — the root tests/conftest.py imports sqlalchemy at module level
       # (for the DB fixtures), so pytest cannot even collect in a DB-free env.

{rootsign-0.2.0 → rootsign-0.2.1}/.github/workflows/release.yml

@@ -22,8 +22,8 @@ jobs:
     permissions:
       id-token: write # required for Trusted Publishing (OIDC)
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
 
@@ -48,4 +48,10 @@ jobs:
           twine check dist/*
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        # Pinned to an immutable commit SHA, not the mutable `release/v1`
+        # branch. This step runs with `id-token: write` and mints the OIDC
+        # token that PyPI Trusted Publishing exchanges for upload rights to
+        # the `rootsign` project — anyone able to move that branch could
+        # publish a release under our name. SHA below == tag v1.14.2.
+        # Bump deliberately; verify the new SHA against the release tag.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

{rootsign-0.2.0 → rootsign-0.2.1}/CONTRIBUTING.md

@@ -20,6 +20,7 @@ docker-compose up -d db          # PostgreSQL + TimescaleDB
 rootsign-admin init              # alembic upgrade head
 python -m pytest tests/unit/ -v          # unit tests (no DB needed at runtime — see note)
 python -m pytest tests/integration/ -v   # integration tests (needs DB)
+python -m pytest -m benchmark -v         # performance budgets (opt-in — see note)
 ```
 
 > **Python:** RootSign requires Python 3.11 or 3.12. We do not support 3.10 or below.
@@ -29,6 +30,12 @@ python -m pytest tests/integration/ -v   # integration tests (needs DB)
 > **Always invoke pytest as `python -m pytest`.** If you `brew install`-ed pytest, the system binary will resolve ahead of the venv's pytest on PATH and run under the system Python — which does not see your venv's site-packages and will fail with confusing `ModuleNotFoundError` (typically on `sqlalchemy` first). `python -m pytest` always uses the venv's interpreter.
 >
 > **Note on unit tests:** The session-scoped `_bootstrap_test_db` fixture in `tests/conftest.py` runs alembic against the test DB before any test (including unit tests). Bring `docker-compose up -d db` up first.
+>
+> **Performance benchmarks are opt-in.** Everything under `tests/performance/` is marked `benchmark` and is **skipped** by a default `python -m pytest` run; pass `-m benchmark` to execute it. These tests assert wall-clock budgets, so they are the most hardware-sensitive part of the suite — `test_1000_actions_under_2_seconds` has only ~1.36x headroom on a developer laptop. They are deliberately kept out of every CI gating job: a timing budget that reddens `main` for reasons unrelated to the diff teaches people to ignore red. Run them locally (or on purpose in CI) when touching the ingest, hashing, or verify paths.
+>
+> **The thresholds are ACs and do not move.** To keep them honest without making them flaky, each budget is sampled several times and asserted on the **median** (`tests/performance/_bench.py`). A single stalled run barely shifts a median, while a real regression shifts every sample — so the AC stays exactly as specified and the measurement stops reacting to background load, cold caches, or a noisy neighbour. Failures print every sample, not just the median, so you can see the spread. `test_p99_overhead_under_5ms` is the exception: it already asserts on the p99 of 1,000 calls, so it is a distribution by construction.
+>
+> These numbers are still **hardware- and environment-dependent** — they measure your disk, your Postgres tuning, and whatever else the machine is doing. Treat a failure as a prompt to investigate on an idle machine, not as proof of a regression. For scale: a trial run of `test_1000_actions_under_2_seconds` produced samples of 1.6s / 2.4s / 1.4s on an idle laptop; the 2.4s sample alone exceeds the 2.0s budget, which is exactly why the median exists.
 
 ## Branch naming
 

{rootsign-0.2.0 → rootsign-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rootsign
-Version: 0.2.0
+Version: 0.2.1
 Summary: RootSign — tamper-evident provenance logging for AI agents (powered by Providex AI)
 Author: Providex AI Inc.
 License: Apache-2.0
@@ -89,7 +89,7 @@ Compliance-grade audit trails. Zero changes to your agent code.
 
 ## Status
 
-**v0.2.0.** `pip install rootsign` → a verified hash chain in under a minute: no Docker, no database, no plumbing. LangGraph + CrewAI integrations, a framework-agnostic MCP proxy, `rootsign verify` CLI, PII redaction, human-in-the-loop checkpoints, opt-in decision capture (PRD-19 / ADR-008), and opt-in SDK micro-batching are all shipping.
+**v0.2.1.** `pip install rootsign` → a verified hash chain in under a minute: no Docker, no database, no plumbing. LangGraph + CrewAI integrations, a framework-agnostic MCP proxy, `rootsign verify` CLI, PII redaction, human-in-the-loop checkpoints, opt-in decision capture (PRD-19 / ADR-008), and opt-in SDK micro-batching are all shipping.
 
 | Phase | Scope | Status |
 |---|---|---|

{rootsign-0.2.0 → rootsign-0.2.1}/README.md

@@ -27,7 +27,7 @@ Compliance-grade audit trails. Zero changes to your agent code.
 
 ## Status
 
-**v0.2.0.** `pip install rootsign` → a verified hash chain in under a minute: no Docker, no database, no plumbing. LangGraph + CrewAI integrations, a framework-agnostic MCP proxy, `rootsign verify` CLI, PII redaction, human-in-the-loop checkpoints, opt-in decision capture (PRD-19 / ADR-008), and opt-in SDK micro-batching are all shipping.
+**v0.2.1.** `pip install rootsign` → a verified hash chain in under a minute: no Docker, no database, no plumbing. LangGraph + CrewAI integrations, a framework-agnostic MCP proxy, `rootsign verify` CLI, PII redaction, human-in-the-loop checkpoints, opt-in decision capture (PRD-19 / ADR-008), and opt-in SDK micro-batching are all shipping.
 
 | Phase | Scope | Status |
 |---|---|---|

{rootsign-0.2.0 → rootsign-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rootsign"
-version = "0.2.0"
+version = "0.2.1"
 description = "RootSign — tamper-evident provenance logging for AI agents (powered by Providex AI)"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"

{rootsign-0.2.0 → rootsign-0.2.1}/rootsign/cli.py

@@ -18,16 +18,24 @@ import re
 import shutil
 import subprocess
 import time
-from importlib import resources
+from importlib import import_module, resources
 from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
-import psycopg2
 import typer
-from alembic import command
-from alembic.config import Config
 
 from rootsign.config import settings
 
+if TYPE_CHECKING:
+    from alembic.config import Config
+
+# psycopg2 and alembic live in the optional `postgres` extra (ADR-011), so they
+# are imported inside the commands that need them via `_require()`. At module
+# level they made `rootsign-admin` unusable on a bare install — even
+# `rootsign-admin --help` and the docker-only `start-db` / `stop-db` died with
+# ModuleNotFoundError before Typer could dispatch. Same defect class as the
+# `rootsign` console script (rootsign/sdk/cli.py).
+
 app = typer.Typer(
     name="rootsign-admin",
     help="RootSign Phase 0 — schema and storage operations (powered by Providex AI).",
@@ -35,6 +43,24 @@ app = typer.Typer(
     no_args_is_help=True,
 )
 
+
+def _require(module: str) -> Any:
+    """Import an optional DB-stack module, or exit with the install hint.
+
+    Mirrors `rootsign.sdk.cli._session_factory`: a missing `postgres` extra
+    becomes a one-line actionable error and exit 1, never a raw traceback.
+    """
+    try:
+        return import_module(module)
+    except ModuleNotFoundError as exc:
+        from rootsign.errors import RootSignPostgresExtraRequired
+
+        typer.echo(
+            f"Error: {RootSignPostgresExtraRequired(f'missing module: {exc.name}')}",
+            err=True,
+        )
+        raise typer.Exit(code=1) from exc
+
 # Default container name + image. Mirrors docker-compose.yml so devs can swap
 # freely between `rootsign-admin start-db` and `docker-compose up -d db`.
 _DB_CONTAINER = "rootsign-timescaledb"
@@ -61,7 +87,7 @@ def _alembic_config(sync_url: str | None = None) -> Config:
     are set directly, so PyPI users (who have no alembic.ini) and devs in the
     repo root behave identically.
     """
-    cfg = Config()
+    cfg = _require("alembic.config").Config()
     cfg.set_main_option("script_location", str(_migrations_dir()))
     cfg.set_main_option("sqlalchemy.url", sync_url or settings.DATABASE_URL_SYNC)
     return cfg
@@ -77,7 +103,8 @@ def _dsn_role() -> str:
 
 
 def _drop_public_schema() -> None:
-    from psycopg2 import sql
+    psycopg2 = _require("psycopg2")
+    sql = _require("psycopg2.sql")
 
     dsn = _strip_driver(settings.DATABASE_URL_SYNC)
     role = sql.Identifier(_dsn_role())
@@ -211,6 +238,9 @@ def init(
     ),
 ) -> None:
     """Apply migrations to the dev database. Use --reset to start from scratch."""
+    # Resolve the DB stack before any output or the destructive --reset prompt,
+    # so a missing extra fails cleanly instead of half-way through.
+    alembic_command = _require("alembic.command")
     start = time.perf_counter()
     if reset:
         # audit #11b: --reset drops the ENTIRE public schema. Require an
@@ -225,7 +255,7 @@ def init(
         typer.echo("Dropping public schema...")
         _drop_public_schema()
     typer.echo("Running alembic upgrade head...")
-    command.upgrade(_alembic_config(), "head")
+    alembic_command.upgrade(_alembic_config(), "head")
     elapsed = time.perf_counter() - start
     typer.echo(f"Done in {elapsed:.2f}s")
 
@@ -233,6 +263,7 @@ def init(
 @app.command()
 def status() -> None:
     """Print row counts for every RootSign table."""
+    psycopg2 = _require("psycopg2")
     dsn = _strip_driver(settings.DATABASE_URL_SYNC)
     conn = psycopg2.connect(dsn)
     try:

{rootsign-0.2.0 → rootsign-0.2.1}/rootsign/errors.py

@@ -24,6 +24,8 @@ import from here without back-edges.
 
 from __future__ import annotations
 
+from contextlib import contextmanager
+from collections.abc import Iterator
 from uuid import UUID
 
 
@@ -194,6 +196,35 @@ class RootSignPostgresExtraRequired(RootSignError):
         super().__init__(message)
 
 
+@contextmanager
+def postgres_extra_required() -> "Iterator[None]":
+    """Translate a missing DB stack into `RootSignPostgresExtraRequired`.
+
+    Wrap the lazy imports of any code path that needs Postgres::
+
+        with postgres_extra_required():
+            from sqlalchemy import select
+
+            from rootsign.database import AsyncSessionLocal
+
+    Since ADR-011 those imports are deferred into function bodies so the core
+    install stays DB-free. Deferring alone only moves *where* the failure
+    happens, though — without this, a user on `pip install rootsign` who calls
+    a DB-backed path gets `ModuleNotFoundError: No module named 'sqlalchemy'`
+    from somewhere deep in the import graph, with no hint that an extra exists.
+    `get_ingest_client` already translated; several SDK entry points did not,
+    so the same mistake produced a helpful message or a bare traceback
+    depending on which door you came through.
+
+    Only wrap the imports themselves. A `ModuleNotFoundError` from unrelated
+    application code inside the block would be mislabelled as a missing extra.
+    """
+    try:
+        yield
+    except ModuleNotFoundError as exc:
+        raise RootSignPostgresExtraRequired(f"missing module: {exc.name}") from exc
+
+
 class HiTLUnsupportedBackendError(RootSignError):
     """`require_approval=True` used with a backend that can't support it here.
 

{rootsign-0.2.0 → rootsign-0.2.1}/rootsign/mcp/server.py

@@ -30,6 +30,8 @@ import logging
 from typing import TYPE_CHECKING, Any, Callable
 from uuid import UUID
 
+from rootsign.errors import postgres_extra_required
+
 if TYPE_CHECKING:
     from contextlib import AbstractAsyncContextManager
 
@@ -45,7 +47,8 @@ logger = logging.getLogger("rootsign.mcp.server")
 def _default_session_factory() -> Any:
     """Lazily resolve the app's AsyncSessionLocal so importing this module
     never constructs a DB engine. Only touched when a tool actually runs."""
-    from rootsign.database import AsyncSessionLocal
+    with postgres_extra_required():
+        from rootsign.database import AsyncSessionLocal
 
     return AsyncSessionLocal()
 
@@ -63,9 +66,10 @@ async def _list_sessions(
     limit: int = 20,
 ) -> list[dict[str, Any]]:
     """Most-recent sessions, optionally filtered by agent, newest first."""
-    from sqlalchemy import select
+    with postgres_extra_required():
+        from sqlalchemy import select
 
-    from rootsign.models.session import AgentSession
+        from rootsign.models.session import AgentSession
 
     async with session_factory() as db:
         stmt = select(AgentSession).order_by(AgentSession.start_time.desc()).limit(limit)
@@ -92,7 +96,8 @@ async def _query_session_chain(
     session_id: str,
 ) -> list[dict[str, Any]]:
     """The ordered Action chain for a session (metadata + hashes, no payloads)."""
-    from rootsign.crud import action as action_crud
+    with postgres_extra_required():
+        from rootsign.crud import action as action_crud
 
     async with session_factory() as db:
         actions = await action_crud.get_session_chain(db, session_id=UUID(session_id))
@@ -118,7 +123,8 @@ async def _verify_session_chain(
     session_id: str,
 ) -> dict[str, Any]:
     """Recompute + verify the chain — identical result to `rootsign verify`."""
-    from rootsign.crud import action as action_crud
+    with postgres_extra_required():
+        from rootsign.crud import action as action_crud
 
     async with session_factory() as db:
         return await action_crud.verify_chain(db, session_id=UUID(session_id))
@@ -130,9 +136,10 @@ async def _get_approval_records(
     action_id: str,
 ) -> list[dict[str, Any]]:
     """All approval rows for an action (a list — escalation can yield several)."""
-    from sqlalchemy import select
+    with postgres_extra_required():
+        from sqlalchemy import select
 
-    from rootsign.models.approval import Approval
+        from rootsign.models.approval import Approval
 
     async with session_factory() as db:
         stmt = (

{rootsign-0.2.0 → rootsign-0.2.1}/rootsign/sdk/chain.py

@@ -20,6 +20,8 @@ from pathlib import Path
 from typing import Any
 from uuid import UUID
 
+from rootsign.errors import postgres_extra_required
+
 
 @dataclass
 class VerifyResult:
@@ -53,7 +55,8 @@ async def verify_session(session_id: UUID, db: Any) -> VerifyResult:
     `db` is an `AsyncSession`. Returns a `VerifyResult`. Never raises on
     chain inconsistency — the result's `valid` field is the verdict.
     """
-    from rootsign.crud import action as action_crud
+    with postgres_extra_required():
+        from rootsign.crud import action as action_crud
 
     raw = await action_crud.verify_chain(db, session_id=session_id)
     return VerifyResult(

{rootsign-0.2.0 → rootsign-0.2.1}/rootsign/sdk/cli.py

@@ -20,15 +20,25 @@ from __future__ import annotations
 
 import asyncio
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
 from uuid import UUID
 
 import typer
 
-# Module-level so tests can monkeypatch it to bind to the test engine.
-# Production code goes through `_verify_remote`, which calls this factory
-# to open a fresh AsyncSession per invocation.
-from rootsign.database import AsyncSessionLocal  # noqa: E402
+# A test seam, deliberately NOT an import. Tests monkeypatch
+# `rootsign.sdk.cli.AsyncSessionLocal` to bind the CLI to the test engine
+# (tests/integration/test_verify_cli.py, test_approve_cli.py,
+# test_show_hn_quickstart.py), so the name has to exist at module scope.
+#
+# Importing `rootsign.database` here to provide it would drag SQLAlchemy in at
+# module-import time, and since ADR-011 the DB stack lives in the optional
+# `postgres` extra. On a no-extras install that made EVERY `rootsign ...`
+# invocation die with ModuleNotFoundError before Typer could dispatch —
+# including `rootsign version` and `rootsign verify --local`, neither of which
+# touches a database. That violates T1.2 / exit criterion 1.
+#
+# `_session_factory()` resolves the real factory on demand instead.
+AsyncSessionLocal: Any = None
 
 app = typer.Typer(
     name="rootsign",
@@ -38,6 +48,31 @@ app = typer.Typer(
 )
 
 
+def _session_factory() -> Any:
+    """Return the AsyncSession factory, importing the DB stack on demand.
+
+    Mirrors `LocalIngestClient._factory` (rootsign/sdk/client.py): a missing
+    `postgres` extra becomes the actionable install hint rather than a bare
+    ModuleNotFoundError from deep in the import graph. Only the DB-backed
+    subcommands call this, so DB-free ones stay usable without the extra.
+    """
+    if AsyncSessionLocal is not None:
+        # Monkeypatched by tests, or already resolved.
+        return AsyncSessionLocal
+    try:
+        from rootsign.database import AsyncSessionLocal as factory
+    except ModuleNotFoundError as exc:
+        from rootsign.errors import RootSignPostgresExtraRequired
+
+        # Reuse the canonical error so the CLI hint can never drift from the SDK's.
+        typer.echo(
+            f"Error: {RootSignPostgresExtraRequired(f'missing module: {exc.name}')}",
+            err=True,
+        )
+        raise typer.Exit(code=1) from exc
+    return factory
+
+
 @app.command()
 def version() -> None:
     """Print the installed RootSign SDK version."""
@@ -99,12 +134,17 @@ def _verify_local(path: Path, verbose: bool) -> None:
 
 
 def _verify_remote(session_id: UUID, verbose: bool) -> None:
-    # Imported at module level (below) so tests can monkeypatch the symbol
-    # to point at a test engine. See tests/integration/test_verify_cli.py.
+    # The session factory is resolved lazily via `_session_factory()`; tests
+    # monkeypatch the module-level `AsyncSessionLocal` seam to point at a test
+    # engine. See tests/integration/test_verify_cli.py.
     from rootsign.sdk.chain import verify_session
 
+    # Resolve the factory up front: a missing `postgres` extra should print the
+    # install hint and exit, not surface from inside asyncio.run().
+    factory = _session_factory()
+
     async def _run():
-        async with AsyncSessionLocal() as db:
+        async with factory() as db:
             return await verify_session(session_id, db)
 
     result = asyncio.run(_run())
@@ -204,12 +244,16 @@ def _list_pending_approvals() -> None:
     Phase 2 will add `--session` and `--owner` filters once multi-tenant
     auth ships.
     """
+    # Before any DB import — otherwise a no-extras install tracebacks on
+    # `from sqlalchemy import select` instead of getting the install hint.
+    factory = _session_factory()
+
     from sqlalchemy import select
 
     from rootsign.models.action import Action
 
     async def _run() -> list[Action]:
-        async with AsyncSessionLocal() as db:
+        async with factory() as db:
             result = await db.execute(
                 select(Action)
                 .where(Action.authorization_status == "pending")
@@ -241,6 +285,9 @@ def _submit_approval(*, action_id: UUID, decision: str, reason: str | None) -> N
     """
     import getpass
 
+    # Before any DB import — see _list_pending_approvals.
+    factory = _session_factory()
+
     from sqlalchemy import select
 
     from rootsign.crud.approval import approval as approval_crud
@@ -256,7 +303,7 @@ def _submit_approval(*, action_id: UUID, decision: str, reason: str | None) -> N
         approver_id = "cli:operator"
 
     async def _run() -> None:
-        async with AsyncSessionLocal() as db:
+        async with factory() as db:
             result = await db.execute(
                 select(Action).where(
                     Action.action_id == action_id,

{rootsign-0.2.0 → rootsign-0.2.1}/rootsign/sdk/client.py

@@ -141,12 +141,10 @@ class ManagedLocalIngestClient(IngestClient):
             return self._session_factory
         # Lazy — the DB stack is the postgres extra (ADR-011). Translate a
         # missing extra into the actionable error, same as get_ingest_client.
-        try:
-            from rootsign.database import AsyncSessionLocal
-        except ModuleNotFoundError as exc:
-            from rootsign.errors import RootSignPostgresExtraRequired
+        from rootsign.errors import postgres_extra_required
 
-            raise RootSignPostgresExtraRequired(f"missing module: {exc.name}") from exc
+        with postgres_extra_required():
+            from rootsign.database import AsyncSessionLocal
         self._session_factory = AsyncSessionLocal
         return self._session_factory