Internal Data Access

CorpData access requirements

Use the approved corpdata.session.UnitOfWork boundary; services must not construct raw SQLAlchemy engines or sessions. Obtain repositories from uow.repositories, write through those repositories, and call uow.commit() exactly once at the application-service boundary.

Golden path:

async with UnitOfWork.for_tenant(tenant_id) as uow:
    customer = await uow.repositories.customers.require(customer_id)
    customer.rename(display_name)
    await uow.commit()

Do not call session.commit() inside a repository: it breaks CorpData's audit outbox and makes multi-repository operations partially durable. Do not catch CorpDataError and return None; translate RecordNotFound at the API boundary and let retryable infrastructure errors reach the company retry middleware.

Tests must use corpdata.testing.FakeUnitOfWork, assert resulting domain state and emitted outbox events, and never mock SQLAlchemy internals. Before handing off, run:

uv run pytest tests/unit tests/contract/corpdata
uv run basedpyright src

Canonical reference: ENG-DATA-014. Stop for data-platform review before adding a new database, bypassing tenant scoping, or changing transaction isolation.